MCP Schema Server

mcp模式服务器

一个零配置MCP服务器框架，直接从简单的manifest.json模式生成功能齐全的模型上下文协议服务器。一次性定义您的工具、提示、资源和元数据，以及 mcp-schema-server 立即将其转换为即用型MCP服务器，无需手动编码。

特性

✨ 零配置 -只需定义您的清单和处理程序\ 🔒 类型安全 -使用TypeScript构建，实现完全类型安全\ ✅ 架构验证 -使用JSON模式（AJV）进行自动输入验证\ 🚀 快速设置 -在几分钟内获得生产就绪的MCP服务器\ 📦 轻量级 -最小的依赖关系，最大的功能

安装

npm install mcp-schema-server

快速开始

1.创建清单文件

创建一个 manifest.json 定义工具、资源和提示的文件：

{
  "tools": [
    {
      "name": "get_user",
      "description": "Get user details by ID",
      "inputSchema": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }
        },
        "required": ["id"]
      }
    }
  ],
  "resources": [
    {
      "uri": "user://all",
      "name": "All Users",
      "mimeType": "application/json",
      "description": "List of all users"
    }
  ],
  "prompts": [
    {
      "name": "analyze_user",
      "description": "Generate user analysis",
      "arguments": [
        {
          "name": "userId",
          "description": "The user ID to analyze",
          "required": true
        }
      ]
    }
  ]
}

2.创建您的服务器

创建一个 server.ts 文件：

import { GenericMcpPlugin } from "mcp-schema-server";
import * as path from "path";

// Define your handler functions
const handlers = {
  // Tool handlers
  "get_user": async (args: { id: string }) => {
    // Your business logic here
    return { id: args.id, name: "John Doe", email: "john@example.com" };
  },
  
  // Resource handlers (use the URI as the key)
  "user://all": async () => {
    return [
      { id: "1", name: "John Doe" },
      { id: "2", name: "Jane Smith" }
    ];
  },
  
  // Prompt handlers
  "analyze_user": async (args: { userId: string }) => {
    return `Please analyze the behavior of user ${args.userId}`;
  }
};

// Initialize and start the server
const plugin = new GenericMcpPlugin({
  name: "my-mcp-server",
  version: "1.0.0",
  manifestPath: path.join(__dirname, "manifest.json"),
  handlers: handlers
});

plugin.start();

3.构建和运行

# Build TypeScript
npx tsc

# Run your server
node dist/server.js

API 参考

GenericMcpPlugin

创建MCP服务器的主类。

构建器选项

interface PluginConfig {
  manifestPath: string;  // Path to your manifest.json file
  name: string;          // Server name
  version: string;       // Server version
  handlers: Record;  // Map of handlers
}

处理程序函数类型

type ActionHandler = (args: any) => Promise | any;

处理程序可以是同步或异步函数，它们：

• 根据您的清单架构接收经过验证的参数
• 返回任何JSON可序列化数据
• 可以抛出将被捕获并返回给客户端的错误

特殊退货类型

图像响应

要返回图像（如图表、示意图），请使用 McpContent 类型：

import { McpContent } from "mcp-schema-server";

const generateChart = async (): Promise => {
  const base64Image = "..."; // your base64 encoded image
  return {
    type: "image",
    data: base64Image,
    mimeType: "image/png"
  };
};

文本回复

常规对象和基元会自动序列化为JSON文本：

const getUser = async (args: { id: string }) => {
  return { id: args.id, name: "John" }; // Auto-converted to JSON
};

清单架构

工具

定义具有输入验证的可调用函数：

{
  "tools": [
    {
      "name": "tool_name",
      "description": "What this tool does",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": { "type": "string" },
          "param2": { "type": "number" }
        },
        "required": ["param1"]
      }
    }
  ]
}

资源

定义可访问的数据资源：

{
  "resources": [
    {
      "uri": "scheme://resource-id",
      "name": "Display Name",
      "mimeType": "application/json",
      "description": "Resource description"
    }
  ]
}

提示

定义提示模板：

{
  "prompts": [
    {
      "name": "prompt_name",
      "description": "What this prompt does",
      "arguments": [
        {
          "name": "arg1",
          "description": "Argument description",
          "required": true
        }
      ]
    }
  ]
}

详细功能

自动输入验证

所有工具输入都会根据JSON模式自动验证：

// If manifest specifies "id" must be a string and is required,
// this is validated BEFORE your handler is called
const getEmployee = (args: { id: string }) => {
  // args.id is guaranteed to be a string here
  return employees.find(e => e.id === args.id);
};

启动完整性检查

启动时，框架会验证：

• ✅ 每个清单工具都有一个相应的处理程序
• ✅ 每个清单资源都有一个相应的处理程序
• ✅ 每个清单提示都有一个相应的处理程序

如果缺少任何处理程序，您将收到一条明确的错误消息：

[MCP Startup Error] Missing handlers for:
 - Tool: get_employee
 - Resource: employee://all
Please add these to your handlers map.

错误处理

处理程序中的错误会被自动捕获并返回给客户端：

const getUser = (args: { id: string }) => {
  const user = users.find(u => u.id === args.id);
  if (!user) {
    throw new Error(`User ${args.id} not found`);
  }
  return user;
};
// Error messages are automatically sent back to the client

示例

看看 examples/ 完整工作示例目录：

• 员工目录 -功能齐全的示例，包括工具、资源和提示

最佳实践

1. 保持处理器纯净 -尽可能避免副作用
2. 使用TypeScript -为您的处理程序提供完全的类型安全
3. 在架构级别进行验证 -让JSON模式处理输入验证
4. 使用有意义的名称 -使您的工具/资源/提示名称具有描述性
5. 记录您的清单 -使用清晰的描述来更好地理解LLM
6. 优雅地处理错误 -抛出描述性错误以进行更好的调试

适配器模式（对开发人员友好）

应用适配器模式可以减少MCP样板，使处理程序更容易编写和重用：

• 彻底简化业务逻辑： 保持你的业务职能（例如。， getEmployee, addEmployee)pure——它们接受参数并返回数据。这使得跨其他接口（REST、CLI）的单元测试和重用变得微不足道。
• 配置优于常规： 将接口定义（描述、模式）移动到 manifest.json 因此，您可以在不更改TypeScript处理程序的情况下更新LLM看到的内容。
• 解决“严格”摩擦： 适配器自动化了MCP SDK响应包装（ { content: [{ type: "text", text: ... }] } shape），让处理程序在常见的95%情况下返回纯JSON。

TypeScript支持

此包使用TypeScript构建，并包含完整的类型定义。你得到：

• 基于您的清单对处理程序参数进行类型推断
• API方法的自动完成
• 编译时类型检查

import { GenericMcpPlugin, McpContent } from "mcp-schema-server";

// Full TypeScript support
const plugin = new GenericMcpPlugin({
  name: "my-server",
  version: "1.0.0",
  manifestPath: "./manifest.json",
  handlers: {
    // TypeScript will help you here
  }
});

发布您的服务器

一旦您构建了MCP服务器：

1. 使用Claude Desktop等MCP客户端进行本地测试
2. 发布到npm： npm publish
3. 用户可以安装和使用： npm install your-mcp-server

需求

• Node.js>=18.0.0
• TypeScript>=5.0（用于开发）

许可证

麻省理工学院© Prantick 这

贡献

欢迎投稿！请随时提交拉取请求。

支持

• 📖 文档
• 💬 问题