Diavgeia MCP Server

This is a Model Context Protocol (MCP) server implementation for the Diavgeia API. It allows AI assistants and other MCP clients to interact with the Greek Transparency Program (Diavgeia) to search for decisions and retrieve decision details.

Features

• MCP Server: Implements the Model Context Protocol using the official Node.js SDK.
• Diavgeia API Integration: Provides 8 tools to interact with the Greek Transparency Program API:
  • Search decisions with advanced filters
  • Retrieve decision details and version history
  • List and query organizations
  • Access decision types and dictionaries
• HTTP Transport: Uses StreamableHTTPServerTransport for stateless communication.
• TypeScript: Built with TypeScript for type safety and maintainability.
• Logging: Integrated logging with Winston (multiple levels).
• Testing: Comprehensive unit and integration tests using Vitest and Zod.
• Header-based Authentication: Accepts credentials via x-diavgeia-username and x-diavgeia-password headers (to be implemented).

Prerequisites

• Node.js (v18 or higher recommended)
• pnpm

Installation

1. Clone the repository:

   git clone <repository-url>
   cd diavgeia-mcp
   

2. Install dependencies:

   pnpm install
   

Configuration

Create a .env file in the root directory to configure the server. You can use the provided example or add your own variables:

PORT=3000
LOG_LEVEL=info
# Rate limiting: requests per second to Diavgeia API (default: 1)
DIAVGEIA_RATE_LIMIT=1
# Optional: Diavgeia API Credentials (if needed for higher rate limits or specific access)
DIAVGEIA_USERNAME=your_username
DIAVGEIA_PASSWORD=your_password

Usage

Building the Project

To build the TypeScript project:

pnpm build

Running the Server

To start the server:

pnpm start

For development with auto-reload:

pnpm dev

The server will start on port 3000 (or the port specified in .env) and listen for MCP requests at the /mcp endpoint.

Connecting an MCP Client

Configure your MCP client to send POST requests to:

• URL: http://localhost:3000/mcp

Authentication (Optional): You can pass Diavgeia credentials via custom headers:

• x-diavgeia-username: Your Diavgeia username
• x-diavgeia-password: Your Diavgeia password

Note: Header-based authentication is configured but not yet implemented in tool calls. Currently, all tools work without authentication for public data.

Example LLM Prompts

Here are some example prompts you can use with an AI assistant connected to this MCP server to explore Greek government transparency data:

Basic Search Examples

1. Search for recent decisions from a municipality:

Find all published decisions from the Municipality of Athens (Δήμος Αθηναίων) from the last 30 days

2. Search for budget-related decisions:

Search for budget commitment decisions (type Β.1.3) from any ministry in October 2025

3. Search by keyword:

Find all decisions related to "προμήθεια" (procurement) from September 2025

Organization Discovery

4. List government organizations:

Show me all active municipalities in Greece

5. Get organization details:

What are the details of organization with UID 99206? Include their full name, status, and website

6. List different organization types:

What categories of organizations are available in Diavgeia? List them with examples

Decision Analysis

7. Get decision details:

Get the full details of decision with ADA ΨΧΦΘ46ΜΠ3Ζ-975. What is it about and who signed it?

8. Track decision changes:

Show me the version history of decision ΒΛΕΖΝ-Ρ7Ν. When was it modified and what changed?

9. Analyze decision types:

What are the main categories of decisions in Diavgeia? Group them by their parent categories

Advanced Queries

10. Cross-reference decisions:

Find all decisions from the Ministry of Education in 2025 related to appointments (τύπος Γ.3.1)

11. Monitor specific organization:

Track all decisions published by organization 50894 in the last week. Summarize the types of decisions they made

12. Dictionary exploration:

What procurement vocabularies (CPV codes) are available? Show me the ones related to construction

Research and Transparency Use Cases

13. Budget tracking:

Find all budget approval decisions from regional authorities in Q1 2025. What's the total amount committed?

14. Personnel monitoring:

Show me all hiring and personnel change decisions from universities in 2025

15. Procurement oversight:

Find procurement award decisions (type Δ.1) over 100,000 EUR from the last 6 months

16. Temporal analysis:

Compare the number of decisions published by municipalities in January vs February 2025. Which were most active?

Multi-step Workflows

17. Organization + Decisions:

First, find the UID for the Municipality of Thessaloniki. Then search for all their decisions from November 2025

18. Type Discovery + Search:

List all decision types related to contracts (συμβάσεις). Then find examples of each type from the last month

19. Dictionary + Filtering:

Get the ORG_CATEGORY dictionary values. Then list all organizations in the "REGION" category

20. Comprehensive Report:

Create a transparency report for organization 30 (Ministry of Interior): 
1. Get their details
2. Find their decisions from the last 3 months
3. Categorize by decision type
4. Highlight any revoked decisions

These prompts demonstrate the MCP server's capabilities for searching, analyzing, and monitoring Greek government transparency data through natural language interactions.

Available Tools

search_decisions

Search for decisions in Diavgeia based on various criteria.

Arguments:

• query (string, optional): General search term.
• org (string, optional): Organization ID or latin name.
• type (string, optional): Decision type ID.
• from_date (string, optional): From date (YYYY-MM-DD).
• to_date (string, optional): To date (YYYY-MM-DD).
• status (enum, optional): Decision status (published, revoked, pending_revocation, all). Default: published.
• page (number, optional): Page number (0-based). Default: 0.
• size (number, optional): Page size. Default: 20.
• sort (enum, optional): Sort order (recent, relative). Default: recent.

get_decision_details

Get detailed information about a specific decision using its ADA (Internet Upload Number).

Arguments:

• ada (string, required): The ADA of the decision.

get_organizations

Get a list of organizations from Diavgeia.

Arguments:

• status (enum, optional): Organization status (active, inactive, pending). Default: active.
• category (string, optional): Organization category code from ORG_CATEGORY dictionary.

get_decision_types

Get a list of all available decision types.

Arguments: None.

get_organization_details

Get detailed information about a specific organization by its UID.

Arguments:

• uid (string, required): The unique identifier of the organization.

get_decision_history

Get the version history of a decision by its ADA.

Arguments:

• ada (string, required): The ADA of the decision.

get_dictionaries

Get a list of all available dictionaries (e.g., ORG_CATEGORY, CPV, CURRENCY).

Arguments: None.

get_dictionary_values

Get values for a specific dictionary by its UID.

Arguments:

• uid (string, required): The unique identifier of the dictionary (e.g., ORG_CATEGORY, CPV).

Development

Testing

Run the unit tests using Vitest:

pnpm test

Project Structure

• src/: Source code
  • tools/: MCP tool implementations
  • utils/: Utility functions (API client, logger)
  • types/: TypeScript type definitions
  • index.ts: Main server entry point
• tests/: Unit tests
• docs/: Documentation

License

ISC