Metadata-Version: 2.4
Name: cfabric-mcp
Version: 0.1.7
Summary: MCP server for Context Fabric corpus operations
Author: Cody Kingham
License: MIT
Project-URL: Homepage, https://context-fabric.ai
Project-URL: Repository, https://github.com/Context-Fabric/context-fabric
Project-URL: Issues, https://github.com/Context-Fabric/context-fabric/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: context-fabric>=0.2.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: uvicorn>=0.32.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Provides-Extra: docs
Requires-Dist: griffe>=1.0; extra == "docs"
Requires-Dist: griffe-typingdoc>=0.2; extra == "docs"

# Context-Fabric MCP Server

Query Context-Fabric corpora via MCP (Model Context Protocol).

## Installation

```bash
pip install cfabric-mcp
```

## Transports

The server supports three transport modes:

| Transport | Flag | Use Case |
|-----------|------|----------|
| stdio | (default) | Claude Desktop, local MCP clients |
| SSE | `--sse PORT` | Cursor, remote MCP clients |
| Streamable HTTP | `--http PORT` | Production deployments |

## Usage

```bash
# stdio transport (Claude Desktop)
cfabric-mcp --corpus /path/to/bhsa

# SSE transport (Cursor, remote clients)
cfabric-mcp --corpus /path/to/bhsa --sse 8000

# Streamable HTTP transport (production)
cfabric-mcp --corpus /path/to/bhsa --http 8000
```

### Options

```bash
--corpus PATH              # Corpus to load (required, repeatable)
--corpus name=PATH         # Named corpus
--sse PORT                 # SSE transport on port (endpoint: /sse)
--http PORT                # Streamable HTTP transport on port (endpoint: /mcp)
--host HOST                # Host to bind (default: 0.0.0.0)
--features "sp lex"        # Load only specific features
--verbose                  # Debug logging
```

## Tools

The server exposes 11 MCP tools organized in layers for efficient discovery.

> **Note:** A usage guide is automatically provided to clients via the MCP `instructions` field at connection time.

### Discovery Tools

| Tool | Description |
|------|-------------|
| `list_corpora` | List loaded corpora |
| `describe_corpus` | Get corpus structure (node types, sections) |
| `list_features` | Browse features with optional node_type filter |
| `describe_feature` | Get feature details with sample values |
| `get_text_formats` | Get text encoding samples (cached) |

### Search Tools

| Tool | Description |
|------|-------------|
| `search` | Pattern search (results/count/statistics/passages) |
| `search_continue` | Paginate search results |
| `search_csv` | Export results to CSV file (stdio only) |
| `search_syntax_guide` | Search syntax docs (section-based) |

### Data Access Tools

| Tool | Description |
|------|-------------|
| `get_passages` | Get text by section references |
| `get_node_features` | Get feature values for nodes |

## Discovery Flow

The tools are designed for hierarchical, iterative discovery:

```
describe_corpus()
│
├─► list_features()                  → Browse all features
│       └─► describe_feature("sp")   → Full details + samples
│
├─► list_features(node_types=["word"])  → Filter by node type
│       └─► describe_feature(...)
│
└─► get_text_formats()               → When encoding matters

        ↓
    search()  → Execute queries
```

**Typical workflow:**
1. `describe_corpus()` - Get structure overview
2. `list_features()` or `list_features(node_types=["word"])` - Browse available features
3. `describe_feature("sp")` - Deep dive into specific feature with sample values
4. `search_syntax_guide()` - Get search syntax help (section-based)
5. `search()` - Execute search queries

### Search Return Types

| Type | Description |
|------|-------------|
| `results` | Paginated node info with cursor (default) |
| `count` | Total count only |
| `statistics` | Feature value distributions |
| `passages` | Formatted text passages |

## Client Configuration

### Claude Desktop (stdio)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "context-fabric": {
      "command": "/path/to/venv/bin/cfabric-mcp",
      "args": ["--corpus", "/path/to/bhsa"]
    }
  }
}
```

### Cursor (SSE)

Start server:
```bash
cfabric-mcp --corpus /path/to/bhsa --sse 8000
```

Configure Cursor to connect to: `http://localhost:8000/sse`

### Custom MCP Clients

For SSE transport, connect to `http://host:port/sse`
For Streamable HTTP, connect to `http://host:port/mcp`

## License

MIT
