Gruenerator Server

CI License: MIT Node.js Version

A Model Context Protocol (MCP) server that gives AI assistants direct access to Green Party political programs from Germany and Austria.

Table of Contents

• Demo
• Features
• Prerequisites
• Installation
• Configuration
• API Reference
• MCP Tools & Resources
• Search Modes
• Contributing
• Acknowledgments
• License

Demo

Coming soon: Demo of search functionality in action

Features

• Hybrid Search - Combines vector and text search with RRF fusion
• German Optimization - Umlaut handling (ä→ae, ö→oe, etc.) and query variants
• Quality Scoring - Results weighted by document quality
• Semantic Caching - Fast responses for repeated queries
• Metadata Filtering - Filter by document type, section, category, etc.
• Filter Discovery - Query available filter values before searching
• MCP Resources - Direct access to collection information and AI guidance

Available Document Collections

Collection	Description	Filters
oesterreich	Die Grünen Austria: EU Election, Basic Program, National Council	title
deutschland	Bündnis 90/Die Grünen: Basic Program, EU Election, Government Program	title
bundestagsfraktion	Green Parliamentary Group: Positions and expert content	section
gruene-de	gruene.de website: Positions, topics, and news	section
gruene-at	gruene.at website: Positions, topics, and news	section
kommunalwiki	KommunalWiki: Municipal politics knowledge (Heinrich Böll Foundation)	article_type, category
boell-stiftung	Heinrich-Böll-Stiftung: Analyses, dossiers, and atlases	content_type, topic, region

Prerequisites

Before you begin, ensure you have:

• Node.js >= 18.0.0
• Qdrant vector database instance (cloud or self-hosted)
• Mistral API key for embedding generation (get one here)

Installation

With Docker (Recommended)

# Build image
docker build -t gruenerator-mcp .

# Run container
docker run -d \
  --name gruenerator-mcp \
  -p 3000:3000 \
  -e QDRANT_URL=https://your-qdrant.com \
  -e QDRANT_API_KEY=your-api-key \
  -e MISTRAL_API_KEY=your-mistral-key \
  gruenerator-mcp

Local Development

# Clone repository
git clone https://github.com/Movm/Gruenerator-MCP.git
cd Gruenerator-MCP

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Start server
npm start

# Or with auto-reload
npm run dev

With Coolify

1. Create a new project
2. Connect Git repository: https://github.com/Movm/Gruenerator-MCP
3. Set environment variables (see below)
4. Deploy

Configuration

Environment Variables

Variable	Description	Required
QDRANT_URL	URL to Qdrant instance	Yes
QDRANT_API_KEY	API key for Qdrant	Yes
MISTRAL_API_KEY	API key for Mistral embeddings	Yes
PORT	Server port	No (default: 3000)
PUBLIC_URL	Public URL for config generation	No
LOG_LEVEL	Log level: DEBUG, INFO, WARN, ERROR	No (default: INFO)

MCP Client Setup

Cursor / Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "gruenerator": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

After configuration, you can ask questions like:

• "Search the Austrian Green programs for climate policy"
• "What does the German Green basic program say about energy transition?"
• "Find municipal politics guidance on waste management in KommunalWiki"
• "What are the Bundestagsfraktion's positions on renewable energy?"
• "Search Böll-Stiftung for analyses on feminism and gender equality"

API Reference

Endpoints

Endpoint	Method	Description
/mcp	POST	MCP communication
/mcp	GET	SSE stream
/mcp	DELETE	End session
/health	GET	Health check with cache and request statistics
/metrics	GET	Detailed server metrics
/.well-known/mcp.json	GET	Auto-discovery metadata
/config/:client	GET	Generate client configuration
/info	GET	Server information

Health Check Response

{
  "status": "ok",
  "service": "gruenerator-mcp",
  "version": "1.0.0",
  "collections": ["oesterreich", "deutschland", "bundestagsfraktion", "gruene-de", "gruene-at", "kommunalwiki", "boell-stiftung"],
  "uptime": { "ms": 3600000, "hours": 1.0 },
  "cache": {
    "embeddingHitRate": "65%",
    "searchHitRate": "42%"
  },
  "requests": { "total": 150, "searches": 120, "errors": 0 },
  "performance": { "avgResponseTimeMs": 250, "cacheHitRate": "65%" }
}

Metrics Response

{
  "server": { "name": "gruenerator-mcp", "version": "1.0.0" },
  "uptime": { "hours": 1.0 },
  "requests": { "total": 150, "searches": 120 },
  "breakdown": {
    "byCollection": { "deutschland": 40, "oesterreich": 30, "kommunalwiki": 25, "bundestagsfraktion": 20, "gruene-de": 15, "gruene-at": 20 },
    "bySearchMode": { "hybrid": 100, "vector": 15, "text": 5 }
  },
  "cache": {
    "embeddings": { "entries": 50, "hitRate": "65%" },
    "search": { "entries": 30, "hitRate": "42%" }
  },
  "memory": { "heapUsedMB": 45, "rssMB": 120 }
}

MCP Tools & Resources

Tools

gruenerator_search

Searches party programs and content with hybrid, vector, or text search.

Parameters:

Parameter	Type	Description	Default
query	string	Search term or question	required
collection	string	Collection to search (see table above)	required
searchMode	string	hybrid, vector, or text	hybrid
limit	number	Maximum number of results (1-20)	5
filters	object	Metadata filters (see below)	optional
useCache	boolean	Use cache	true

Available Filters by Collection:

Filter	Collections	Description
documentType	oesterreich, deutschland	Document type (grundsatzprogramm, wahlprogramm, eu-wahlprogramm)
title	oesterreich, deutschland	Exact document title
section	bundestagsfraktion, gruene-de, gruene-at	Content section (Positionen, Themen, etc.)
article_type	kommunalwiki	Article type (literatur, praxishilfe, faq, etc.)
category	kommunalwiki	Thematic category (Haushalt, Umwelt, etc.)
content_type	boell-stiftung	Content type (artikel, dossier, atlas, schwerpunkt)
topic	boell-stiftung	Topic (klima, feminismus, migration, digitalisierung, etc.)
region	boell-stiftung	Geographic region (afrika, europa, asien, lateinamerika, etc.)

Example:

{
  "query": "climate protection and renewable energy",
  "collection": "kommunalwiki",
  "searchMode": "hybrid",
  "limit": 5,
  "filters": { "article_type": "praxishilfe", "category": "Umwelt" }
}

gruenerator_get_filters

Discovers available filter values for a collection. Use this before filtering to know valid values.

Parameters:

Parameter	Type	Description	Default
collection	string	Collection to get filters for	required

Example Response:

{
  "collection": "KommunalWiki",
  "collectionId": "kommunalwiki",
  "description": "Municipal politics knowledge (Heinrich Böll Foundation)",
  "filters": {
    "article_type": {
      "label": "Article Type",
      "type": "keyword",
      "values": ["literatur", "praxishilfe", "faq", "sachgebiet"],
      "count": 4
    },
    "category": {
      "label": "Category",
      "type": "keyword",
      "values": ["Haushalt", "Umwelt", "Verkehr", "..."],
      "count": 25
    }
  }
}

gruenerator_cache_stats

Shows cache statistics for embeddings and search results.

Parameters: None

Example Response:

{
  "embeddings": { "entries": 50, "hits": 120, "misses": 30, "hitRate": "80%" },
  "search": { "entries": 30, "hits": 80, "misses": 40, "hitRate": "67%" }
}

get_client_config

Generates ready-to-use MCP configurations for various clients.

Parameters:

• client (string, required) - claude, cursor, or vscode

Resources

The server provides the following resources via MCP protocol:

URI	Description
gruenerator://system-prompt	Read first! Usage instructions for AI assistants
gruenerator://info	Server information and capabilities
gruenerator://collections	List of all available collections
gruenerator://collections/{key}	Details of a specific collection (oesterreich, deutschland, bundestagsfraktion, gruene-de, gruene-at, kommunalwiki, boell-stiftung)

Search Modes

Hybrid (Default)

Combines vector and text search with Reciprocal Rank Fusion (RRF). Best results for most queries.

Vector

Pure semantic search based on embeddings. Good for conceptual questions.

Text

Classic text search with German optimizations. Good for exact terms or names.

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue using the bug report template
2. Request features - Open an issue using the feature request template
3. Submit PRs - Fork the repo, create a branch, and submit a pull request

Please ensure your PR:

• Passes CI checks
• Follows existing code style
• Includes appropriate documentation updates

Acknowledgments

• Model Context Protocol - The protocol powering this server
• Qdrant - Vector database for semantic search
• Mistral AI - Embedding generation
• Die Grünen Österreich & Bündnis 90/Die Grünen - Source documents
• Grüne Bundestagsfraktion - Parliamentary group content
• Heinrich-Böll-Stiftung - Political analyses, dossiers, and atlases
• Heinrich-Böll-Stiftung KommunalWiki - Municipal politics knowledge base

License

MIT License - see LICENSE