npm package: @mdp-framework/mcp-server
Description: MCP Server - Expose MDP capabilities as tools for Claude Code, Cursor, and other MCP clients
Author: MDP Framework Contributors
Latest version: 1.1.99

# @mdp-framework/mcp-server

MCP Server implementation for the MDP Framework. Exposes MDP capabilities (policies, memory, evidence) as tools for Claude Code, Cursor, and other MCP clients.

## Features

- **MCP Protocol Compliant**: Implements the [Model Context Protocol](https://modelcontextprotocol.io/specification) specification
- **5 Core Tools**: Policy management, capsule search, and evidence recording
- **Dual Transport**: stdio (for Claude Code/Cursor) and HTTP modes
- **Gateway Integration**: Run via `mlang gateway --mode mcp`

## Installation

```bash
npm install @mdp-framework/mcp-server
```

## Usage

### As a Library

```typescript
import { createMCPServer } from '@mdp-framework/mcp-server';
import { createResolver } from '@mdp-framework/gateway';
import { createCapsuleStore } from '@mdp-framework/gateway/store';
import { PolicyRegistry } from '@mdp-framework/adapters';

// Setup resolver
const registry = new PolicyRegistry({ basePath: '.mlang/policies' });
const resolver = createResolver({ registries: [registry] });

// Setup store
const store = await createCapsuleStore({
  backend: 'file',
  baseDir: '.mlang/state/capsules',
});

// Create and start server
const server = createMCPServer({ resolver, store });
await server.start('stdio'); // or 'http' with port

console.log('MCP server running with', server.getTools().length, 'tools');
```

### Via CLI

```bash
# stdio mode (for Claude Code/Cursor)
mlang gateway --mode mcp --stdio

# HTTP mode (for web clients)
mlang gateway --mode mcp --http --port 8080
```

### Via Standalone Binary

```bash
# stdio mode
npx @mdp-framework/mcp-server

# HTTP mode
npx @mdp-framework/mcp-server --http --port=8080
```

## Available Tools

### 1. policy.get

Get a policy by ID and optional version.

**Input:**
```json
{
  "id": "ios.swift.no-force-unwrap",
  "version": "2025.01.15"  // optional
}
```

**Output:**
```json
{
  "success": true,
  "data": {
    "policy": { /* PolicyCard */ },
    "uri": "policy://org/ios.swift.no-force-unwrap@2025.01.15"
  }
}
```

### 2. policy.search

Search policies by tags, owner, or scope.

**Input:**
```json
{
  "tags": ["ios", "security"],
  "scope": "org",
  "limit": 10
}
```

**Output:**
```json
{
  "success": true,
  "data": {
    "policies": [ /* PolicyCard[] */ ],
    "total": 5
  }
}
```

### 3. memory.get

Get a state capsule by ID.

**Input:**
```json
{
  "id": "capsule://mdp-framework/TEAM_A/pr/pr-123"
}
```

**Output:**
```json
{
  "success": true,
  "data": {
    "capsule": { /* StateCapsule */ }
  }
}
```

### 4. memory.search

Search capsules by natural language query.

**Input:**
```json
{
  "query": "authentication implementation",
  "filters": {
    "kind": "pr",
    "team": "TEAM_A"
  },
  "limit": 5
}
```

**Output:**
```json
{
  "success": true,
  "data": {
    "capsules": [ /* StateCapsule[] */ ],
    "total": 3
  }
}
```

### 5. evidence.record

Attach evidence to a state capsule.

**Input:**
```json
{
  "capsule_id": "capsule://mdp-framework/TEAM_A/pr/pr-123",
  "evidence": {
    "type": "link",
    "ref": "gh://mdp-framework/mdp/PR/123/diff@abc123",
    "title": "PR diff snapshot",
    "metadata": {
      "files_changed": 5,
      "lines": 234
    }
  }
}
```

**Output:**
```json
{
  "success": true,
  "data": {
    "capsule_id": "capsule://mdp-framework/TEAM_A/pr/pr-123",
    "evidence_added": { /* Evidence */ }
  }
}
```

## Claude Code Integration

Add to your `.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mdp-framework": {
      "command": "mlang",
      "args": ["gateway", "--mode", "mcp", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

Then ask Claude:
- "Show me the force unwrap policy"
- "Search for PRs related to authentication"
- "Record this PR diff as evidence for capsule X"

## Cursor Integration

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mdp-framework": {
      "command": "mlang",
      "args": ["gateway", "--mode", "mcp", "--stdio"]
    }
  }
}
```

## Architecture

```
┌─────────────────────────────────────┐
│     MCP Client (Claude Code)        │
└───────────────┬─────────────────────┘
                │ JSON-RPC 2.0
┌───────────────▼─────────────────────┐
│         MCP Protocol Handler        │
│   (tools/list, tools/call, init)    │
└───────────────┬─────────────────────┘
                │
┌───────────────▼─────────────────────┐
│          Tool Handlers              │
│  ┌─────────────────────────────┐   │
│  │ PolicyGetTool               │   │
│  │ PolicySearchTool            │   │
│  │ MemoryGetTool               │   │
│  │ MemorySearchTool            │   │
│  │ EvidenceRecordTool          │   │
│  └─────────────────────────────┘   │
└───────────────┬─────────────────────┘
                │
┌───────────────▼─────────────────────┐
│     Gateway (PolicyResolver,        │
│     CapsuleStore)                   │
└─────────────────────────────────────┘
```

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Type check
npm run typecheck
```

## License

MIT