AI导哈

设计系统HTTP微服务

一个基于NodeJS和Express的HTTP微服务，通过JSON-RPC协议实现MCP协议，用于暴露设计系统的资源。

  • by Thaynah
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Thaynah/mcp-server

使用说明

MCP服务器（HTTP）用于设计系统

一个基于NodeJS（Express）的HTTP微服务，通过JSON-RPC实现MCP协议，以暴露设计系统的资源。数据源为Markdown（本地模拟）或S3。

栈（Stack）

  • NodeJS + Express
  • @modelcontextprotocol/sdk + zod
  • @aws-sdk/client-s3
  • gray-matter

配置

复制 .env.example para .env 并调整：

PORT=3000
MOCK_S3=true
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=changeme
AWS_SECRET_ACCESS_KEY=changeme
S3_BUCKET=meu-bucket-design-system
S3_PREFIX=components/
  • MOCK_S3=true 美国 mock-data/components/*.md。
  • 对于S3真实（或：实际S3）： MOCK_S3=false + 凭据和存储桶。

执行

  • 开发者（Dev）： npm run dev
  • 生产/本地： npm start
  • 基地： http://localhost:3000

终点（或：结局指标）

  • GET /health → { status, service, mock }
  • POST /mcp → JSON-RPC 2.0（通过SDK使用MCP）
  • GET /mcp → 打开SSE（服务器→客户端）会话
  • DELETE /mcp → 结束当前会话

注：组件的REST路由（/components， /components/:id) 已被移除。访问组件仅通过MCP进行。

MCP（官方SDK）

  • 服务器： McpServer com（通常作为域名后缀，表示商业网站） StreamableHTTPServerTransport。
  • 资源： ResourceTemplate('component://{id}') 具有动态列表和Markdown阅读功能。
  • 工具（模式） zod): search_components， related_components。
  • 提示： component_usage。

HTTP调用要求

  • 头球 Accept 必须包括 application/json e text/event-stream。
  • initialize 应该与……一起发送 protocolVersion （例： 2025-03-26）。
  • 之后 initialize，包括 Mcp-Session-Id e Mcp-Protocol-Version 在所有后续通话中。

CURLs（软件开发工具包）

  • 初始化（捕获会话）
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -d '{
   "jsonrpc":"2.0",
   "id":"init",
   "method":"initialize",
   "params":{
     "clientInfo":{"name":"cli","version":"1.0.0"},
     "capabilities":{"jsonResponse":true},
     "protocolVersion":"2025-03-26"
   }
 }'
# Observe o header mcp-session-id na resposta e exporte:
# SID=... (valor do header)
  • 列出资源（重用会话）
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"lr","method":"resources/list","params":{}}'
  • 读取资源（通过URI）
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"rr","method":"resources/read","params":{"uri":"component://button"}}'
  • 列出工具
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"lt","method":"tools/list","params":{}}'
  • 执行工具 search_components
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"ct1","method":"tools/call","params":{"name":"search_components","arguments":{"query":"input"}}}'
  • 运行工具 related_components
curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"ct2","method":"tools/call","params":{"name":"related_components","arguments":{"id":"button"}}}'
  • 专用SSE（可选）
curl -s -N -X GET http://localhost:3000/mcp \
 -H 'Accept: text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26'
  • 结束会议
curl -s -X DELETE http://localhost:3000/mcp \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' -i

结构

src/
  index.js       # Express + transporte MCP
  mcp-setup.js   # Registro de recursos, ferramentas e prompt via SDK
  datasource.js  # S3 + mock
mock-data/
  components/
.env.example
README.md

使用MCP Inspector进行调试

  • 安装并连接：
npx @modelcontextprotocol/inspector
  • 在用户界面，使用以下URL进行连接： http://localhost:3000/mcp。

与MCP客户的连接

  • 克劳德代码：
claude mcp add --transport http design-system http://localhost:3000/mcp
  • VS Code（JSON 示例）：
code --add-mcp '{"name":"design-system","type":"http","url":"http://localhost:3000/mcp"}'

“Coleção Insomnia”可以翻译为“失眠系列”。

  • 进口：
    • 打开Insomnia → 应用程序 → 导入数据 → 从文件导入。
    • 选择文件 insomnia_mcp_collection.json 在项目的根基上。
  • 环境：
    • 该系列已经确定 base_url （http://localhost:3000e protocol_version (2025-03-26）。
  • 会话链接：
    • 请求 Initialize (capture session) 捕获标题（或头部信息） mcp-session-id。
    • 其他请求会自动使用这个值与模板一起 {% response 'req_init', 'header', 'mcp-session-id' %}.
  • 建议的顺序：
    • Health → Initialize (capture session) → resources/list → resources/read (button) → tools/list → tools/call search_components → tools/call related_components → prompts/list → prompts/get component_usage (id=button) → GET SSE /mcp （可选）→ DELETE /mcp。
  • 备注：
    • 确保服务器正在运行（PORT=3000 MOCK_S3=true node src/index.js）。
    • O SSE（服务器发送事件）是持续的；完成后手动停止。

相关 MCP