使用说明
mcp试剂盒
通用MCP（模型上下文协议）工具包 用于构建跨所有JavaScript运行时运行的MCP服务器。
特性
- 🌍 通用运行时支持：单个代码库适用于Node.js、Bun、Cloudflare Workers、Vercel Edge、Netlify Edge和其他JavaScript环境
- ⚡ Hono框架：超快速、轻量级的HTTP框架，零冷启动
- 🔄 跨运行时兼容性：自动运行时检测和条件功能加载
- 🧰 类型安全工具处理器：带有验证的强类型MCP工具定义
- 📦 多目标建筑：针对不同运行时环境的单独优化版本
- 🛠️ 框架不可知：通用构建中没有外部依赖
本地运行时特性（Node.js/Bun）
- 🔀 多实例协调：基于锁的主/代理模式，具有自动角色分配功能
- 🔄 基于版本的升级：部署新版本时无缝过渡
- 🌐 反向代理网关：用于负载分配的轻量级HTTP代理
- 🔌 STDIO代理：通过STDIO传输转发MCP请求（兼容Claude Desktop）
- 🚪 港口管理：自动端口分配、冲突解决和清理
- ♻️ 整个生命周期：优雅的关机处理程序和信号管理
- 🔒 死锁恢复：自动清理崩溃的实例锁
安装
npm install github:omar391/mcp-kit
# or
pnpm add github:omar391/mcp-kit
快速开始
import { createHonoMcpServer } from '@omar391/mcp-kit/server/core/hono-mcp';
import { createToolHandlers } from '@omar391/mcp-kit/server/handlers';
const toolHandlers = createToolHandlers([
{
name: 'greet',
description: 'Greet someone by name',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string' }
},
required: ['name']
},
handler: async ({ name }) => ({
content: [{ type: 'text', text: `Hello, ${name}!` }]
})
}
]);
const app = createHonoMcpServer({
serverInfo: { name: 'my-mcp-server', version: '1.0.0' },
toolHandlers
});
// Deploy anywhere:
// - Node.js: app.listen(3000)
// - Cloudflare Workers: export default { fetch: app.fetch }
// - Vercel Edge: export default app
建筑
┌─────────────────────────────────────────────────────────┐
│ Your MCP Server │
└─────────────────────────────────────────────────────────┘
│
├─ Runtime Detection
│
┌──────────────────┴──────────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────┐
│ Universal Core │ │ Local Features │
│ (All Runtimes) │ │ (Node.js/Bun) │
│ │ │ │
│ • Hono Server │ │ • Instance Mgmt │
│ • Tool Handlers │ │ • Proxy Gateway │
│ • Middleware │ │ • Port Manager │
│ • Type System │ │ • Process Mgmt │
└──────────────────┘ └────────────────────┘
│ │
└─────────────┬───────────────────────┘
▼
┌──────────────────────────┐
│ Deployment Target │
├──────────────────────────┤
│ • Node.js / Bun │
│ • Cloudflare Workers │
│ • Vercel Edge │
│ • Netlify Edge │
│ • Deno │
└──────────────────────────┘
运行时兼容性
| 运行时 | 通用核心 | 本地功能 | 注释 |
|---|---|---|---|
| Node.js | ✅ | ✅ | 全功能支持 |
| Bun | ✅ | ✅ | 全功能支持 |
| Cloudflare员工 | ✅ | ❌ | 仅限通用 |
| Vercel Edge | ✅ | ❌ | 仅限通用 |
| Netlify Edge | ✅ | ❌ | 仅限通用 |
| Deno | ✅ | ❌ | 仅限通用 |
| 浏览器 | ✅ | ❌ | 仅限通用 |
多实例协调
仅在Node.js/Bun环境中可用
架构概述
┌─────────────────────────┐
│ Lock File System │
│ /tmp/mcp-kit-{port}.lock│
└───────────┬─────────────┘
│
First process acquires lock
│
┌───────────────────────┴───────────────────────┐
│ │
▼ ▼
┌───────────────┐ ┌──────────────────┐
│ MAIN │ │ PROXY INSTANCES │
│ INSTANCE │ │ (HTTP or STDIO) │
│ │ │ │
│ • Holds Lock │◄───── Forward Requests ────┤ • No Lock │
│ • Port: 8989 │ │ • Auto Port │
│ • Runs Tools │ │ • Transparent │
└───────┬───────┘ └────────▲─────────┘
│ │
│ │
├─ Control Endpoints: │
│ • /__version │
│ • /__shutdown │
│ • /__transition │
│ │
└──────────────┬───────────────────────────────┘
│
▼
┌────────────────┐
│ MCP Clients │
│ (Claude, etc.) │
└────────────────┘
运作原理
1.基于锁的选举
- 第一个实例创建锁文件→ 成为MAIN
- 后续实例检测锁→ 成为代理人
2.版本管理
- 新版本检测到旧MAIN
- 通过请求优雅过渡
/__transition - 旧MAIN成为代理，新MAIN成为MAIN
- 无缝升级，无需停机
3.死锁恢复
- 检测崩溃的进程（PID检查）
- 自动清除陈旧的锁
- 如果需要，将代理提升到MAIN
4.代理模式
- HTTP模式：反向代理转发所有请求
- STDIO模式：用于Claude Desktop集成的MCP客户端代理
版本升级流程
Time ──────────────────────────────────────────────►
┌─────────────────┐
│ MAIN v1.0.0 │ Running, handling requests
│ Port: 8989 │
└────────┬────────┘
│
│ New deployment starts
│
▼
┌─────────────────┐ ┌─────────────────┐
│ MAIN v1.0.0 │ │ NEW v2.0.0 │
│ Port: 8989 │ │ Detects lock │
└────────┬────────┘ └────────┬────────┘
│ │
│◄──── POST /__transition ───┤
│ │
▼ │
┌─────────────────┐ │
│ Becomes PROXY │ │
│ Removes lock │ │
└─────────────────┘ │
▼
┌─────────────────┐
│ MAIN v2.0.0 │
│ Port: 8989 │
│ Handles reqs │
└─────────────────┘
API 参考
核心功能
| 功能 | 运行时 | 描述 |
|---|---|---|
createHonoMcpServer(options) |
通用 | 在Hono框架上创建MCP服务器 |
createToolHandlers(tools) |
通用 | 类型安全工具处理程序定义 |
startMcpServer(config) |
Node.js/Bun | 高级协调启动器 |
detectRuntime() |
通用 | 获取运行时信息 |
isNodeLike() |
通用 | 检查Node.js还是Bun |
本地特性（Node.js/Bun）
| 组件 | 目的 |
|---|---|
InstanceManager |
锁的多实例协调 |
ProxyManager |
HTTP反向代理网关 |
coordinateInstanceRole() |
自动主/代理选举 |
startStdioProxy() |
STDIO传输代理 |
ensurePortAvailable() |
港口冲突解决 |
registerSignalHandlers() |
优雅的停机处理 |
有关API使用的详细信息，请参阅内联文档和TypeScript类型。
使用示例
基本服务器
import { startMcpServer, createToolHandlers } from '@omar391/mcp-kit/server';
await startMcpServer({
serverName: 'my-server',
serverVersion: '1.0.0',
toolHandlers: createToolHandlers([/* tools */]),
defaultPort: 8989
});
使用生命周期挂钩
await startMcpServer({
serverName: 'my-server',
serverVersion: '1.0.0',
toolHandlers,
localMode: {
onLocalStart: async (instanceManager) => {
console.log(`Main instance on port ${instanceManager.port}`);
},
onShutdown: async (instanceManager) => {
await instanceManager.removeLock();
}
}
});
边缘运行时（通用）
import { createHonoMcpServer } from '@omar391/mcp-kit/server/core/hono-mcp';
const app = createHonoMcpServer({ serverInfo, toolHandlers });
// Cloudflare Workers
export default { fetch: app.fetch };
// Vercel Edge
export const config = { runtime: 'edge' };
export default app;
STDIO模式（克劳德桌面）
node server.js --mode=stdio
构建目标
该软件包提供了多个构建目标以实现最佳部署：
universal：适用于任何地方，没有Node.js API（默认）node：包括Node.js特定的功能和APIbrowser：浏览器环境的最小构建
使用条件导出自动获得正确的构建：
{
"imports": {
"@omar391/mcp-kit": {
"node": "@omar391/mcp-kit/dist/node/index.js",
"default": "@omar391/mcp-kit/dist/index.js"
}
}
}
故障排除
| 问题 | 解决方案 |
|---|---|
| 端口已在使用中 | 使用运行 --kill-existing 旗帜或 lsof -i :PORT 检查 |
| 失效锁文件 | 如果进程失效，则自动清理，或手动清理： rm /tmp/mcp-kit-{port}.lock |
| 版本冲突 | 新版本自动请求转换 /__transition 端点 |
| 代理未连接 | 验证主实例是否正在运行，并且没有防火墙阻止本地主机 |
| 锁定权限 | 确保 /tmp 可写，进程具有文件权限 |
许可证
麻省理工学院
