JS MCP Server

JS MCP 服务

带有 WASM SDK 的 JavaScript MCP 服务组件，便于集成和部署。

设置

要开始使用 JS MCP 服务，请按以下步骤操作：

git clone https://github.com/justin-echternach/js-mcp-server.git
cd js-mcp-server
npm install -g @bytecodealliance/componentize-js @bytecodealliance/jco
npm install

构建

要构建项目并生成 WebAssembly 模块：

npm run build

这会使用 Vite 打包 JavaScript 代码，并将其组件化为 dist/js-mcp-server.wasm。

自定义

你可以通过添加或修改处理器（也称为工具）来自定义服务。处理器在 server.js 文件中注册，并位于 handlers 目录中。要添加新的处理器：

1. 在 handlers 目录中创建一个新的 JavaScript 文件，实现你的处理器。
2. 在 server.js 中导入你的处理器。
3. 在 createMcpServer 函数调用中的 tools 对象里添加你的处理器，方式与添加 EchoTool、KgTool 和 FetchDogTool 类似。

例如，要添加一个名为 MyCustomTool 的新处理器：

// In server.js
import { MyCustomTool } from './handlers/index.js';

createMcpServer({
  serverInfo: {
    name: "JavaScript MCP Server",
    version: "1.0.0"
  },
  tools: {
    [EchoTool.name]: EchoTool,
    [KgTool.name]: KgTool,
    [MyCustomTool.name]: MyCustomTool
  },
  handlers: {
    // Custom handlers (optional)
  }
});

编写自定义处理器

处理器（工具）是服务功能的核心。每个处理器都应导出：

• 一个用于处理请求并返回结果的异步处理函数。
• 用于输入验证和文档说明的名称（字符串）、描述和架构。

最简示例

下面是一个基于 FetchDogTool 的最简处理器：

// handlers/fetch_dog_tool.js
export async function handleTool(parameters) {
  try {
    // Perform your logic (e.g., HTTP request)
    return { result: 'success!' };
  } catch (error) {
    return { error: error.message };
  }
}

export function getToolName() {
  return 'fetch_dog';
}

export function getToolDescription() {
  return 'Fetches a random dog image from the Dog API';
}

export function getToolSchema() {
  return { type: 'object', properties: {} };
}

export const FetchDogTool = {
  handler: handleTool,
  name: getToolName(),
  description: getToolDescription(),
  schema: getToolSchema()
};

注册处理器

1. 在 handlers/index.js 中导出：

   import { FetchDogTool } from './fetch_dog_tool.js';
   export { FetchDogTool };
   // ...add to tools map if needed
   

2. 将其添加到 server.js 中的 tools 对象：

   import { FetchDogTool } from './handlers/fetch_dog_tool.js';
   createMcpServer({
     tools: {
       [FetchDogTool.name]: FetchDogTool,
       // ...other tools
     }
   });
   

最佳实践

• 处理器可以是 async，并返回普通对象。
• 始终妥善处理错误，并返回清晰的错误对象。
• 使用 schema 属性描述预期输入。
• 添加有意义的 name 和 description 字段，以便于发现。

如需更高级的功能（超时、重试、更完善的错误处理），可以相应扩展处理器逻辑。

---

使用 Postgres 和 HTTP 接口

你的 MCP 服务可以通过健壮且便于开发者使用的抽象，与 HTTP API、Postgres 数据库等外部服务交互。

Postgres 接口（异步）

你可以使用 comapi:postgres/[email protected] 接口中的 query 函数查询 Postgres 数据库。这对知识图谱或数据驱动的工具很有用。

示例：

import { query } from "comapi:postgres/[email protected]";

export async function handleTool(parameters) {
  const entityFilter = parameters?.entityFilter || "";
  const sqlQuery = `
    SELECT id, name FROM my_table
    WHERE name ILIKE $1
    LIMIT 10
  `;
  const inputValue = `%${entityFilter}%`;
  // PgValue enum/variant: { tag: 'text', val: value }
  const params = [{ tag: 'text', val: inputValue }];
  const result = await query(sqlQuery, params);
  return { rows: result.rows };
}

最佳实践：

• WIT 定义的枚举/变体在文本输入时必须包装为 { tag: 'text', val: value }。
• 始终验证并清理输入。
• 根据需要使用 try/catch 处理错误。

HTTP 客户端函数

SDK 提供了便于开发者使用的 HTTP 客户端抽象，用于发送 HTTP 请求，并封装了 WASI HTTP 的复杂性。

示例：

import { get } from '../sdk/http/index.js';

export async function handleTool(parameters) {
  try {
    // Simple GET request with JSON response
    const response = await get('https://dog.ceo/api/breeds/image/random', { json: true });
    return { image_url: response.message, status: response.status };
  } catch (error) {
    return { error: error.message };
  }
}

可用的 HTTP 方法：

• get(url, options)
• post(url, data, options)
• put(url, data, options)
• patch(url, data, options)
• del(url, options)（别名：deleteRequest）
• head、options、postJson、putJson、patchJson、postForm、putForm
• 你也可以通过 createHttpClient 创建自定义 HTTP 客户端。

最佳实践：

• 使用 json: true 选项自动解析 JSON 响应。
• 使用 try/catch 处理错误，并返回清晰的错误对象。