@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 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

npm install @mdp-framework/mcp-server

Usage

As a Library

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

# 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

# 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:

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

Output:

{
  "success": true,
  "data": {
    "policy": { /* PolicyCard */ },
    "uri": "policy://org/[email protected]"
  }
}

2. policy.search

Search policies by tags, owner, or scope.

Input:

{
  "tags": ["ios", "security"],
  "scope": "org",
  "limit": 10
}

Output:

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

3. memory.get

Get a state capsule by ID.

Input:

{
  "id": "capsule://mdp-framework/TEAM_A/pr/pr-123"
}

Output:

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

4. memory.search

Search capsules by natural language query.

Input:

{
  "query": "authentication implementation",
  "filters": {
    "kind": "pr",
    "team": "TEAM_A"
  },
  "limit": 5
}

Output:

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

5. evidence.record

Attach evidence to a state capsule.

Input:

{
  "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:

{
  "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:

{
  "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:

{
  "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

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

License

MIT