MCP 服务器

Digital Twin MCP Server

MCP server for Digital Twin learner data, providing tools for AI Guide to explore metamodel and manage twin data with access control.

README

Digital Twin MCP Server

Тип репозитория: DS/instrument

MCP (Model Context Protocol) server for Digital Twin learner data. Provides tools for AI Guide (Проводник) to work with learner profiles based on 4-type indicator classification.

Overview

This server implements a metamodel-driven approach with 3 MCP tools and 4 indicator types (IND.1-4).

Key Features

3 MCP Tools for metamodel exploration and data management
4-Type Classification (IND.1-4) with access control
65+ Indicators organized in hierarchical structure
Dual Deployment - stdio for local MCP clients + HTTP API for Cloudflare Workers

Architecture

┌─────────────────────────────────────┐
│  AI Guide (LLM with MCP client)     │
│  - Analyzes learner state           │
│  - Calls MCP tools                  │
│  - Provides guidance                │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  MCP Server (this project)          │
│  - 3 tools                          │
│  - Access control (IND.1 writable)  │
│  - Metamodel-driven                 │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  Data Store                         │
│  - Metamodel (MD files)             │
│  - Twin data (PostgreSQL/Neon)      │
│  - OAuth state (Cloudflare KV)      │
└─────────────────────────────────────┘

Available Tools

Tool	Description
`describe_by_path`	Navigate metamodel structure. List categories, groups, indicators
`read_digital_twin`	Read data from digital twin by path
`write_digital_twin`	Write data to digital twin (1_declarative only for users)

Installation

Prerequisites

Node.js 18+
npm or yarn
Cloudflare account (for deployment)
Neon PostgreSQL database (for persistent twin data storage)

Install Dependencies

npm install

Usage

Option 1: Local MCP Server (stdio)

For use with MCP clients like Claude Desktop:

node src/index.js

Add to your MCP client configuration:

{
  "mcpServers": {
    "digital-twin": {
      "command": "node",
      "args": ["/path/to/digital-twin-mcp/src/index.js"]
    }
  }
}

Option 2: Cloudflare Workers (HTTP API)

Local Development

npm run dev

This starts the development server at http://localhost:8787

Test Endpoints

# Health check
curl http://localhost:8787/

# List all tools
curl http://localhost:8787/tools

# Describe metamodel root
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "describe_by_path",
    "arguments": {"path": "/"}
  }'

Deploy to Cloudflare

Uses Cloudflare GitHub App for automatic deployment on push to main.

Set secrets before first deploy:

npx wrangler secret put ORY_CLIENT_SECRET --env ory-auth
npx wrangler secret put DATABASE_URL --env ory-auth

Manual deployment:

npm run deploy -- --env ory-auth

API Examples

Explore Metamodel

# List all categories
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "describe_by_path", "arguments": {"path": "/"}}'

# List subgroups in 1_declarative
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "describe_by_path", "arguments": {"path": "1_declarative"}}'

# List indicators in goals subgroup
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "describe_by_path", "arguments": {"path": "1_declarative/1_2_goals"}}'

# Read specific indicator definition
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "describe_by_path", "arguments": {"path": "1_declarative/1_2_goals/09_Цели обучения"}}'

Read Twin Data

# Read all data
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_digital_twin", "arguments": {"path": "/"}}'

# Read specific path
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_digital_twin", "arguments": {"path": "indicators.agency"}}'

Write Twin Data

# Write to 1_declarative (allowed)
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "write_digital_twin",
    "arguments": {
      "path": "1_declarative/goals/learning",
      "data": ["Learn TypeScript", "Master MCP"]
    }
  }'

# Write to 2_collected (denied for users)
curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "write_digital_twin",
    "arguments": {
      "path": "2_collected/time/total",
      "data": 100
    }
  }'
# Returns: {"error": "Access denied: users cannot write to 2_collected"}

Testing

Run tests:

npm test

Test stdio server directly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/index.js

Development

Project Structure

digital-twin-mcp/
├── src/
│   ├── index.js              # MCP server (stdio, file-based storage)
│   ├── worker-sse.js         # Cloudflare Worker (PostgreSQL/Neon storage)
│   └── metamodel-data.js     # Generated metamodel data
├── metamodel/                # MD files defining indicators
├── data/
│   └── twin.json             # Twin data store (stdio mode only)
├── scripts/
│   └── build-metamodel.js    # Regenerate metamodel-data.js
├── package.json
├── wrangler.toml             # Cloudflare config
└── README.md

Adding New Indicators

Determine type (IND.1-4)
Place MD file in correct category/subgroup folder
Use format: NN_Name.md

Include required metadata:

# IND.X.Y.Z

**Name:** Indicator name
**Name (EN):** English name
**Type:** semantic|temporal|categorical
**Format:** string|float|enum|structured_text

Regenerate data: node scripts/build-metamodel.js
Run tests: npm test