Gruenerator MCP Server

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

<!-- Add screenshot or GIF of MCP client using Gruenerator --> 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

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

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

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:

Available Filters by Collection:

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:

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:

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