Metadata-Version: 2.4
Name: xframework-mcp
Version: 0.1.0
Summary: MCP server for XframeworkID — query the registry of labelled bond disclosure documents from Claude and other MCP clients
Project-URL: Homepage, https://xframework.id
Project-URL: Repository, https://github.com/iandhoward/XframeworkID
Project-URL: Documentation, https://xframework.id/llms.txt
Author-email: Ian Howard <ihoward@vectorbravo.com>
License: MIT License
        
        Copyright (c) 2026 Ian Howard
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: esg,green-bonds,labelled-bonds,mcp,spo,xframeworkid
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# XframeworkID MCP Server

[Model Context Protocol](https://modelcontextprotocol.io) server that exposes the [XframeworkID](https://xframework.id) registry of labelled bond disclosure documents (frameworks, SPOs, impact reports, assurance, certifications, EU GBS reviews, academic research) to Claude and other MCP clients.

## What it does

Lets a Claude conversation:

- Resolve any **XFID** (document), **XPID** (person), or **XOID** (organization) to its registry data
- Search ~10,800 documents by query, type, year, country
- Look up issuers and their full disclosure chains
- Look up analysts, researchers, issuance staff, bankers and their published work
- Find related documents (framework ↔ SPO ↔ impact ↔ assurance)
- Cite XFIDs in responses with permanent URLs

All queries hit the public xframework.id JSON API — no authentication required, no local database needed.

## Installation

### From PyPI (recommended once published)

```bash
pip install xframework-mcp
```

### From source

```bash
git clone https://github.com/iandhoward/XframeworkID.git
cd XframeworkID/mcp_server
pip install -e .
```

## Configure Claude Desktop

Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "xframework-id": {
      "command": "xframework-mcp"
    }
  }
}
```

Restart Claude Desktop. You should see a 🔌 icon indicating MCP servers are connected.

## Configure other MCP clients

The server uses stdio transport. For any MCP client, run:

```bash
xframework-mcp
```

It will read MCP messages from stdin and write to stdout.

## Tools provided

| Tool | Purpose |
|---|---|
| `about_xframework` | Returns project summary, scale, identifier types, key findings. Useful as a first orientation call. |
| `resolve_id` | Resolve any XFID / XPID / XOID to its registry data (with or without dashes). |
| `search_documents` | Search by free-text query + filters (type, year, country). Returns up to 50 results. |
| `get_issuer` | Get an issuer's profile and all their documents by slug. |
| `get_disclosure_chain` | For a document XFID, return the full chain (framework + SPO + impact + assurance + ISINs). |
| `list_top_analysts` | Get the SPO or CBI certification analyst leaderboard URL. |
| `find_research_papers` | Find academic research papers about labelled bonds (RESEARCH document type). |

## Example queries Claude can answer with this server

- "What are all the disclosure documents Iberdrola has published?"
- "Show me the framework, SPO, and impact reports for the IFC Forests Bond."
- "Find academic papers about greenium pricing."
- "Who reviewed the Conservation Fund's Working Forests Green Bond?"
- "What's at XFID `XF-A3B7K2M-9`?"
- "List all 2025 SPOs in the registry."
- "What documents has Caroline Flammer published in this registry?"

## Technical notes

- **HTTP client**: `httpx.AsyncClient` with a 15s timeout, `User-Agent: xframework-mcp/0.1.0`.
- **Caching**: relies on the API's `Cache-Control` headers (60s for search, 300s for documents).
- **Error handling**: tool calls return JSON `{"error": "..."}` payloads on failure rather than raising.
- **No authentication**: only reads public registry data. No secrets, no rate limits beyond the public API's.

## What this server does NOT do

- Submit corrections or new documents (use https://xframework.id/contact).
- Access paid features (investor comparison tool, page view tracking).
- Modify the registry. Read-only.

## License

MIT. See repository root.

## About XframeworkID

XframeworkID is an open registry that assigns permanent, content-based identifiers (XFIDs) to extra-financial disclosure documents associated with labelled bond issuances. Founded by Ian Howard (ex-Sustainalytics SPO business lead, ex-Climate Bonds Initiative data lead). The registry exists because 23% of these documents have already disappeared from their published URLs — see [Deleting the Receipts](https://xframework.id/research/deleting-the-receipts).

For full documentation see https://xframework.id/llms-full.txt.
