henreh/cpr-kg-mcp

Climate Policy Radar MCP Server

A FastMCP server that exposes climate law & policy knowledge graph to agentic clients. This server provides primitive, composable KG actions for finding relevant law/policy passages with provenance, traversing climate concepts via Wikibase, and comparing across jurisdictions.

Features

• Deep-Research Compatible: Implements search and fetch tools for seamless integration with ChatGPT Deep Research
• Climate Policy Data: Access to comprehensive climate law and policy documents via HuggingFace datasets
• Concept Store Integration: SPARQL-based access to CPR Wikibase for climate concept relationships
• Evidence-Based: All results include full provenance with document metadata and passage locations
• Dockerized: Production-ready containerized deployment with caching support

Quick Start

Using Docker (Recommended)

1. Clone the repository:

git clone https://github.com/yourusername/kg-mcp.git
cd kg-mcp

2. Copy environment configuration:

cp .env.example .env
# Edit .env with your configuration (optional HF_TOKEN for private datasets)

3. Run with Docker Compose:

docker-compose up -d

The server will be available at http://localhost:8000.

Local Development

1. Install dependencies with uv:

uv sync

2. Set environment variables:

export DATA_CACHE_DIR=./cache
export DATASET_REPO=ClimatePolicyRadar/all-document-text-data
export DATASET_REVISION=main
export SPARQL_ENDPOINT=https://climatepolicyradar.wikibase.cloud/query/sparql

3. Run the server:

uv run python -m server.server

API Tools

Deep-Research Compatible Tools

search

Generic retrieval over passages with optional filters.

{
  "query": "solar energy policy",
  "filters": {
    "iso3": ["BRA", "ZAF"],
    "language": ["en"],
    "concept_qids": ["Q1167"]
  },
  "limit": 50
}

fetch

Hydrate resource IDs to full Evidence objects.

{
  "ids": ["cpr://doc/brazil-climate-law#p=123"]
}

Concept Store Tools

concept_find

Search concepts by label, alias, or QID.

concept_neighbors

Get 1-hop or 2-hop neighborhood of a concept in the knowledge graph.

concept_properties

Get frequency of properties used globally or for a specific concept.

concept_mentions

Find passages likely mentioning specific concepts.

Document & Jurisdiction Tools

family_overview

Group documents by policy family.

jurisdiction_overview

Get distribution summaries for a jurisdiction.

compare_jurisdictions

Side-by-side comparison of two jurisdictions.

policy_lineage

Follow policy family history.

Admin Tools

health

Check system health and connectivity.

list_resources

Enumerate available views and cache status.

Data Sources

1. Document Dataset: Climate Policy Radar's all-document-text-data from HuggingFace
2. Concept Store: CPR Wikibase SPARQL endpoint at https://climatepolicyradar.wikibase.cloud/query/sparql

Evidence Schema

All evidence objects follow this structure:

{
  "id": "cpr://doc/{slug}#p={index}",
  "document": {
    "slug": "string",
    "document_id": "string",
    "title": "string",
    "family_title": "string",
    "geographies": ["ISO3"],
    "languages": ["en"],
    "url": "https://app.climatepolicyradar.org/documents/{slug}"
  },
  "passage": {
    "index": 123,
    "page_number": 4,
    "type": "body",
    "text": "...exact text..."
  },
  "concept_matches": [
    {
      "qid": "Q1167",
      "label": "Solar energy",
      "match_type": "label",
      "offsets": [[0, 12]]
    }
  ],
  "score": 0.85
}

Testing

Run the test suite:

uv run pytest tests/ -v

With coverage:

uv run pytest tests/ --cov=server --cov-report=html

Configuration

See .env.example for all available configuration options.

Authentication (Optional)

The server supports multiple authentication providers:

• Azure AD
• Eunomia (policy-based)
• Permit.io (RBAC/ABAC)

Enable by setting the appropriate environment variables.

Performance

• Caching: Downloaded datasets are cached locally with TTL
• SPARQL: Results cached for 5 minutes to reduce endpoint load
• Indexing: DuckDB views optimize for common query patterns
• Scoring: BM25-like ranking for relevance

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• Climate Policy Radar for the dataset and Wikibase
• FastMCP framework for MCP implementation
• DuckDB for efficient data processing