captain-drawdown-mcp 0.1.0__tar.gz

captain_drawdown_mcp-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+
+# Refactor pause flag — touched manually, never committed
+.analytics-refactor-in-progress

captain_drawdown_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: captain-drawdown-mcp
+Version: 0.1.0
+Summary: MCP server for Captain Drawdown's open carbon dioxide removal data: companies, researchers, shops.
+Project-URL: Homepage, https://captaindrawdown.com/api/
+Project-URL: Data, https://captaindrawdown.com/data/
+Author-email: Captain Drawdown / Carbon Drawdown Initiative <info@carbon-drawdown.de>
+License: MIT
+Keywords: CDR,carbon removal,climate,mcp,open data
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2
+Description-Content-Type: text/markdown
+
+# captain-drawdown-mcp
+
+An MCP server that gives Claude, ChatGPT, Cursor and other MCP clients direct access to Captain Drawdown's open data on carbon dioxide removal (CDR):
+
+- **Companies**: 969 published CDR companies with pathway, country, liveliness tier, EU SME size class, registries and evidence dates (CC BY-NC-SA 4.0).
+- **Researchers**: 95,000+ researchers with CDR papers since 2021, aggregated by country and pathway, plus top-100 lists per pathway (CC BY 4.0).
+- **Shops**: shops where individuals buy certified removal, with prices (CC BY 4.0).
+
+It reads the public static API at `https://captaindrawdown.com/api/v1/` (no key, CORS open) and caches responses for six hours. Every result carries `version`, `as_of`, `license` and `cite_as`.
+
+## Install
+
+```bash
+pip install captain-drawdown-mcp      # or: uvx captain-drawdown-mcp
+```
+
+Claude Desktop / Claude Code (`claude mcp add captain-drawdown -- captain-drawdown-mcp`) or `claude_desktop_config.json`:
+
+```json
+{"mcpServers": {"captain-drawdown": {"command": "captain-drawdown-mcp"}}}
+```
+
+Cursor (`.cursor/mcp.json`): same `command`. Any client that speaks MCP over stdio works.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `stats()` | headline numbers of the newest release |
+| `search_companies(query, country_code, pathway, size_class, region, limit)` | matching companies with slugs |
+| `company(slug)` | one company |
+| `countries()`, `pathways()` | companies per country / per pathway |
+| `researchers_by_country()`, `researchers_by_pathway()` | listed researchers with the calibrated estimate |
+| `top_researchers(pathway, region, limit)` | top 100 worldwide or top 50 in Europe for a pathway |
+| `shops()` | shops with prices |
+| `cite()` | citation and licences |
+
+## Data and licences
+
+Pages: https://captaindrawdown.com/data/ · API: https://captaindrawdown.com/api/ · Corrections: info@carbon-drawdown.de. The server code is MIT; the data keeps its own licences (companies CC BY-NC-SA 4.0 because the directory is seeded from Grant Faber's list; researchers and shops CC BY 4.0).
+
+Captain Drawdown is a project of the Carbon Drawdown Initiative (Fürth, Germany).

captain_drawdown_mcp-0.1.0/README.md

@@ -0,0 +1,42 @@
+# captain-drawdown-mcp
+
+An MCP server that gives Claude, ChatGPT, Cursor and other MCP clients direct access to Captain Drawdown's open data on carbon dioxide removal (CDR):
+
+- **Companies**: 969 published CDR companies with pathway, country, liveliness tier, EU SME size class, registries and evidence dates (CC BY-NC-SA 4.0).
+- **Researchers**: 95,000+ researchers with CDR papers since 2021, aggregated by country and pathway, plus top-100 lists per pathway (CC BY 4.0).
+- **Shops**: shops where individuals buy certified removal, with prices (CC BY 4.0).
+
+It reads the public static API at `https://captaindrawdown.com/api/v1/` (no key, CORS open) and caches responses for six hours. Every result carries `version`, `as_of`, `license` and `cite_as`.
+
+## Install
+
+```bash
+pip install captain-drawdown-mcp      # or: uvx captain-drawdown-mcp
+```
+
+Claude Desktop / Claude Code (`claude mcp add captain-drawdown -- captain-drawdown-mcp`) or `claude_desktop_config.json`:
+
+```json
+{"mcpServers": {"captain-drawdown": {"command": "captain-drawdown-mcp"}}}
+```
+
+Cursor (`.cursor/mcp.json`): same `command`. Any client that speaks MCP over stdio works.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `stats()` | headline numbers of the newest release |
+| `search_companies(query, country_code, pathway, size_class, region, limit)` | matching companies with slugs |
+| `company(slug)` | one company |
+| `countries()`, `pathways()` | companies per country / per pathway |
+| `researchers_by_country()`, `researchers_by_pathway()` | listed researchers with the calibrated estimate |
+| `top_researchers(pathway, region, limit)` | top 100 worldwide or top 50 in Europe for a pathway |
+| `shops()` | shops with prices |
+| `cite()` | citation and licences |
+
+## Data and licences
+
+Pages: https://captaindrawdown.com/data/ · API: https://captaindrawdown.com/api/ · Corrections: info@carbon-drawdown.de. The server code is MIT; the data keeps its own licences (companies CC BY-NC-SA 4.0 because the directory is seeded from Grant Faber's list; researchers and shops CC BY 4.0).
+
+Captain Drawdown is a project of the Carbon Drawdown Initiative (Fürth, Germany).

captain_drawdown_mcp-0.1.0/captain_drawdown_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Captain Drawdown MCP server package."""
+__version__ = "0.1.0"

captain_drawdown_mcp-0.1.0/captain_drawdown_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m captain_drawdown_mcp` starts the stdio server."""
+from .server import main
+
+main()

captain_drawdown_mcp-0.1.0/captain_drawdown_mcp/data.py

@@ -0,0 +1,111 @@
+"""Data access for the Captain Drawdown MCP server: reads the static JSON API
+(https://captaindrawdown.com/api/v1/) and filters in memory. No mcp import
+here so the logic is testable without the SDK."""
+import json
+import time
+from typing import Callable, Optional
+from urllib.request import Request, urlopen
+
+API_BASE = "https://captaindrawdown.com/api/v1"
+CACHE_TTL_S = 6 * 3600
+
+
+def _http_get(url: str) -> dict:
+    req = Request(url, headers={"User-Agent": "captain-drawdown-mcp/0.1 (+https://captaindrawdown.com/api/)"})
+    with urlopen(req, timeout=30) as r:
+        return json.loads(r.read().decode("utf-8"))
+
+
+class Api:
+    """Small cached client. `fetch` is injectable for tests."""
+
+    def __init__(self, base: str = API_BASE, fetch: Optional[Callable[[str], dict]] = None,
+                 ttl_s: int = CACHE_TTL_S):
+        self.base = base.rstrip("/")
+        self.fetch = fetch or _http_get
+        self.ttl = ttl_s
+        self._cache = {}
+
+    def get(self, path: str) -> dict:
+        now = time.time()
+        hit = self._cache.get(path)
+        if hit and now - hit[0] < self.ttl:
+            return hit[1]
+        data = self.fetch(f"{self.base}/{path.lstrip('/')}")
+        self._cache[path] = (now, data)
+        return data
+
+    # ── tools ──────────────────────────────────────────────────────────
+    def stats(self) -> dict:
+        return self.get("stats.json")
+
+    def company(self, slug: str) -> dict:
+        slug = (slug or "").strip().lower()
+        if not slug:
+            return {"error": "slug required"}
+        try:
+            return self.get(f"companies/{slug}.json")
+        except Exception:
+            return {"error": f"unknown slug {slug!r}; use search_companies to find the slug"}
+
+    def search_companies(self, query: str = "", country_code: str = "", pathway: str = "",
+                         size_class: str = "", region: str = "", limit: int = 25) -> dict:
+        env = self.get("companies.json")
+        rows = env.get("data", [])
+        q = (query or "").strip().lower()
+        cc = (country_code or "").strip().upper()
+        pw = (pathway or "").strip().lower()
+        sc = (size_class or "").strip().lower()
+        rg = (region or "").strip().lower()
+        out = []
+        for c in rows:
+            if q and q not in f"{c.get('name', '')} {c.get('description', '')} {c.get('pathway_primary', '')}".lower():
+                continue
+            if cc and (c.get("country_code") or "").upper() != cc:
+                continue
+            if pw and pw not in (c.get("pathway_primary") or "").lower():
+                continue
+            if sc and sc not in (c.get("size_class") or "").lower():
+                continue
+            if rg and rg not in (c.get("region") or "").lower():
+                continue
+            out.append({k: c.get(k) for k in ("name", "slug", "country", "country_code", "region",
+                                               "pathway_primary", "liveliness_tier", "size_class",
+                                               "url", "profile_url")})
+        limit = max(1, min(int(limit or 25), 200))
+        return {"version": env.get("version"), "as_of": env.get("as_of"), "license": env.get("license"),
+                "cite_as": env.get("cite_as"), "matches": len(out), "data": out[:limit]}
+
+    def countries(self) -> dict:
+        return self.get("countries.json")
+
+    def pathways(self) -> dict:
+        return self.get("pathways.json")
+
+    def researchers_by_country(self) -> dict:
+        return self.get("researchers/by-country.json")
+
+    def researchers_by_pathway(self) -> dict:
+        return self.get("researchers/by-pathway.json")
+
+    def top_researchers(self, pathway: str, region: str = "global", limit: int = 25) -> dict:
+        slug = (pathway or "").strip().lower().replace(" ", "-")
+        try:
+            env = self.get(f"researchers/top/{slug}.json")
+        except Exception:
+            idx = self.get("index.json")
+            return {"error": f"unknown pathway {pathway!r}", "pathways": idx.get("pathway_slugs", [])}
+        key = "europe_top50" if (region or "").lower().startswith("eu") else "global_top100"
+        rows = env.get("data", {}).get(key, [])
+        limit = max(1, min(int(limit or 25), 100))
+        return {"version": env.get("version"), "as_of": env.get("as_of"), "license": env.get("license"),
+                "cite_as": env.get("cite_as"), "pathway": env.get("data", {}).get("pathway"),
+                "ranking": key, "data": rows[:limit]}
+
+    def shops(self) -> dict:
+        return self.get("shops.json")
+
+    def cite(self) -> dict:
+        idx = self.get("index.json")
+        return {"version": idx.get("version"), "as_of": idx.get("as_of"), "cite_as": idx.get("cite_as"),
+                "licenses": idx.get("licenses"), "data_pages": idx.get("data_pages")}

captain_drawdown_mcp-0.1.0/captain_drawdown_mcp/server.py

@@ -0,0 +1,87 @@
+"""Captain Drawdown MCP server: carbon removal companies, researchers and shops
+for Claude, ChatGPT, Cursor and other MCP clients. Reads the public static API
+at https://captaindrawdown.com/api/v1/ (no key). Run: `captain-drawdown-mcp`."""
+from mcp.server.fastmcp import FastMCP
+
+from .data import Api
+
+mcp = FastMCP("captain-drawdown",
+              instructions=("Open data on carbon dioxide removal (CDR): a directory of CDR companies, "
+                            "a census of CDR researchers and shops that sell certified removal. Every result "
+                            "carries version, as_of, license and cite_as: quote them when you use the numbers. "
+                            "Companies are CC BY-NC-SA 4.0, researchers and shops CC BY 4.0."))
+api = Api()
+
+
+@mcp.tool()
+def stats() -> dict:
+    """Headline numbers of the newest Captain Drawdown data release (companies, researchers, shops)."""
+    return api.stats()
+
+
+@mcp.tool()
+def search_companies(query: str = "", country_code: str = "", pathway: str = "", size_class: str = "",
+                     region: str = "", limit: int = 25) -> dict:
+    """Search published carbon removal companies. Filters: free text (name, description), ISO country
+    code (e.g. DE), pathway (e.g. DAC, Biochar, BECCS, Enhanced Weathering), size class (micro, small,
+    medium, large), region (EU27, Europe, United States, China). Returns slugs for `company`."""
+    return api.search_companies(query, country_code, pathway, size_class, region, limit)
+
+
+@mcp.tool()
+def company(slug: str) -> dict:
+    """One company by slug (from search_companies): pathway, country, liveliness tier, size class,
+    registries, evidence dates, description and profile URL."""
+    return api.company(slug)
+
+
+@mcp.tool()
+def countries() -> dict:
+    """Published carbon removal companies per country (ISO 3166-1 alpha-2)."""
+    return api.countries()
+
+
+@mcp.tool()
+def pathways() -> dict:
+    """Published carbon removal companies per primary pathway."""
+    return api.pathways()
+
+
+@mcp.tool()
+def researchers_by_country() -> dict:
+    """CDR researchers (at least one CDR paper since 2021) per country, with the calibrated estimate."""
+    return api.researchers_by_country()
+
+
+@mcp.tool()
+def researchers_by_pathway() -> dict:
+    """CDR researchers per primary pathway."""
+    return api.researchers_by_pathway()
+
+
+@mcp.tool()
+def top_researchers(pathway: str, region: str = "global", limit: int = 25) -> dict:
+    """Top researchers for a pathway (biochar, soil-carbon, general-cdr, dac, ocean-cdr,
+    enhanced-weathering, beccs), ranked by CDR papers since 2021 with a citation rank; region
+    'global' (top 100) or 'europe' (top 50)."""
+    return api.top_researchers(pathway, region, limit)
+
+
+@mcp.tool()
+def shops() -> dict:
+    """Shops where individuals can buy certified carbon removal, with prices, methods and certifiers."""
+    return api.shops()
+
+
+@mcp.tool()
+def cite() -> dict:
+    """How to cite the datasets: version, as_of, cite_as per dataset, licences, data pages."""
+    return api.cite()
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

captain_drawdown_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "captain-drawdown-mcp"
+version = "0.1.0"
+description = "MCP server for Captain Drawdown's open carbon dioxide removal data: companies, researchers, shops."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Captain Drawdown / Carbon Drawdown Initiative", email = "info@carbon-drawdown.de" }]
+keywords = ["mcp", "carbon removal", "CDR", "climate", "open data"]
+dependencies = ["mcp>=1.2,<2"]
+
+[project.urls]
+Homepage = "https://captaindrawdown.com/api/"
+Data = "https://captaindrawdown.com/data/"
+
+[project.scripts]
+captain-drawdown-mcp = "captain_drawdown_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["captain_drawdown_mcp"]