MCP SDK

@开路导线/mcp-sdk

用于构建生产就绪MCP服务器的标准SDK。

停止复制粘贴样板。获取错误处理、验证、日志记录、遥测和 单线货币化 开箱即用。

](https://www.npmjs.com/package/@openconductor/mcp-sdk) ](https://www.npmjs.com/package/@openconductor/mcp-sdk)  

为什么选择这个SDK？

每个MCP服务器都需要相同的东西：

全力以赴 ~20kb，无需配置。

安装

npm install @openconductor/mcp-sdk

要求： Node.js 18+

🎮 零配置演示模式

v1.4中的新功能： 无需API密钥即可立即开始构建！

import { initOpenConductor, initTelemetry, requirePayment } from '@openconductor/mcp-sdk'

// That's it! Demo mode activates automatically
initOpenConductor({ serverName: 'my-server' })

// All features work - telemetry logs to console, payments are mocked
const telemetry = initTelemetry()  // Logs to console in demo mode
const paidTool = requirePayment({ credits: 10 })(myHandler)  // Always allows, 9999 mock credits

演示模式提供：

• ✅ 模拟计费 --始终允许，9999学分，无实际费用
• ✅ 控制台遥测 --本地记录所有指标以进行调试
• ✅ 全型安全 --与生产相同的类型和接口
• ✅ 零设置 --只需导入并执行即可

当您准备好进行生产时，只需添加您的API密钥：

initOpenConductor({ 
  apiKey: process.env.OPENCONDUCTOR_API_KEY,
  serverName: 'my-server' 
})

快速开始

import { 
  initOpenConductor,
  wrapTool, 
  validateInput, 
  z, 
  createLogger,
  initTelemetry 
} from '@openconductor/mcp-sdk'

// Initialize the SDK (demo mode if no API key)
initOpenConductor({
  serverName: 'my-server',
  serverVersion: '1.0.0',
  // apiKey: 'oc_xxx'  // Add for production
})

// Enable observability (console in demo, API in production)
initTelemetry()

// Create a validated, wrapped tool in seconds
const searchTool = wrapTool(
  validateInput(
    z.object({
      query: z.string().min(1),
      limit: z.number().int().positive().default(10)
    }),
    async (input) => {
      // input is typed: { query: string, limit: number }
      return { results: await db.search(input.query, input.limit) }
    }
  ),
  { name: 'search', timeout: 5000 }
)

// Automatic error handling, logging, and telemetry
const result = await searchTool({ query: 'hello', limit: 5 })

特性

🛡️ 错误处理

具有丰富上下文的JSON-RPC 2.0兼容错误：

import { ValidationError, ToolExecutionError } from '@openconductor/mcp-sdk/errors'

throw new ValidationError('amount', 'Must be positive', -5)
// → { code: -32602, message: "Validation failed...", data: { field, reason, value } }

包括10种错误类型： ValidationError，ToolNotFoundError，ToolExecutionError，ResourceNotFoundError、AuthenticationError，AuthorizationError，RateLimitError，TimeoutError，DependencyError，ConfigurationError

→ 错误处理指南

✅ 验证

Zod配备了MCP特定的助手：

import { validateInput, z, schemas } from '@openconductor/mcp-sdk'

const handler = validateInput(
  z.object({
    query: schemas.nonEmptyString,
    limit: schemas.limit,      // 1-100, default 10
    email: schemas.email,
    url: schemas.url,
  }),
  async (input) => doSomething(input)  // Fully typed!
)

→ 验证指南

📝 日志记录

适用于任何日志聚合器的结构化JSON：

import { createLogger } from '@openconductor/mcp-sdk/logger'

const log = createLogger('my-server', { level: 'info', pretty: true })

log.info('Tool invoked', { tool: 'search', userId: 'abc' })
// {"timestamp":"...","level":"info","service":"my-server","message":"Tool invoked","tool":"search","userId":"abc"}

const toolLog = log.child({ requestId: 'req_123' })  // Scoped context

🔧 服务器实用工具

健康检查和工具包装：

import { createHealthCheck, wrapTool } from '@openconductor/mcp-sdk/server'

// Standard health endpoint
const healthCheck = createHealthCheck({
  name: 'my-server',
  version: '1.0.0',
  checks: {
    database: async () => db.ping(),
    redis: async () => redis.ping(),
  }
})
// → { status: 'healthy', checks: { database: true, redis: true }, ... }

// Wrap any handler with production features
const safeTool = wrapTool(myHandler, {
  name: 'my-tool',
  timeout: 5000,  // Auto-timeout
})

📊 遥测

生产环境可选的可观察性（演示模式下的控制台日志记录）：

import { initOpenConductor, initTelemetry } from '@openconductor/mcp-sdk'

// Demo mode - logs to console
initOpenConductor({ serverName: 'my-server' })
initTelemetry()
// [🎮 DEMO] Telemetry track: { tool: "search", duration: "45ms", success: true }

// Production mode - sends to OpenConductor
initOpenConductor({
  apiKey: 'oc_xxx',
  serverName: 'my-server',
})
initTelemetry()

// All wrapped tools automatically report:
// ✓ Invocation counts
// ✓ Success/failure rates
// ✓ Latency percentiles (p50, p95, p99)
// ✓ Error messages

隐私： 仅发送工具名称、持续时间和错误。从不输入、输出或用户数据。

→ 遥测指南

💰 单线货币化

使用积分、订阅或每次通话收取MCP工具的费用：

import { initOpenConductor, initPayment, requirePayment } from '@openconductor/mcp-sdk'

// Demo mode - mock billing (always allowed, 9999 credits)
initOpenConductor({ serverName: 'my-server' })
initPayment()  // Auto-configures for demo mode

// Production mode
initOpenConductor({ apiKey: 'oc_xxx', serverName: 'my-server' })
initPayment()

// Credits-based
const paidTool = requirePayment({ credits: 10 })(myHandler)

// Subscription tier
const premiumTool = requirePayment({ tier: 'pro' })(myHandler)

// Works with wrapTool
const safePaidTool = wrapTool(
  requirePayment({ credits: 5 })(myHandler),
  { name: 'premium-analysis' }
)

→ 货币化指南

可摇动的进口树木

只导入您需要的内容：

// Full SDK
import { z, validate, wrapTool, createLogger, requirePayment } from '@openconductor/mcp-sdk'

// Or specific modules (smaller bundles)
import { ValidationError } from '@openconductor/mcp-sdk/errors'
import { z, validate } from '@openconductor/mcp-sdk/validate'
import { createLogger } from '@openconductor/mcp-sdk/logger'
import { wrapTool } from '@openconductor/mcp-sdk/server'
import { initTelemetry } from '@openconductor/mcp-sdk/telemetry'
import { requirePayment } from '@openconductor/mcp-sdk/payment'

文档

• 入门指南 --构建您的第一台服务器
• 错误处理 --所有错误类型和用法
• 验证 --模式模式和助手
• 遥测 --可观察性设置
• 变现 --单线支付门
• api参考 -完整的API文件

例子

完整MCP服务器

看 示例/完整服务器 为了完整实施。

FastMCP集成

import FastMCP from 'fastmcp'
import { wrapTool, validateInput, z } from '@openconductor/mcp-sdk'

const server = new FastMCP({ name: 'my-server' })

server.addTool({
  name: 'greet',
  description: 'Generate a greeting',
  parameters: z.object({ name: z.string() }),
  execute: wrapTool(
    validateInput(z.object({ name: z.string() }), async ({ name }) => {
      return `Hello, ${name}!`
    }),
    { name: 'greet', timeout: 5000 }
  )
})

贡献

欢迎投稿！看 贡献.md.

许可证

MIT© 开放式导体