MCPB 开发指南

什么是 MCPB？

MCPB (MCP Bundle) 是 Desktop Extensions 的新文件格式，用于打包 MCP 服务器及其所有依赖项到单个可安装包中。

文件扩展名更新

旧格式：.dxt (Desktop Extension)
新格式：.mcpb (MCP Bundle)
兼容性：现有的 .dxt 扩展将继续工作，但建议新扩展使用 .mcpb

开发环境设置

1. 安装 MCPB 工具

npm install -g @anthropic-ai/mcpb

2. 初始化项目

mcpb init

这将创建基本的项目结构和示例文件。

项目结构

my-extension/
├── manifest.json         # 扩展清单（必需）
├── server/               # MCP 服务器代码
│   ├── index.js         # 主入口文件
│   └── utils.js         # 工具函数
├── package.json         # Node.js 依赖
├── node_modules/        # 依赖包
├── icon.png            # 扩展图标
└── README.md           # 文档

Manifest 配置详解

必需字段

{
  "mcpb_version": "0.1",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "Extension description",
  "author": {
    "name": "Your Name"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  }
}

可选字段

{
  "display_name": "My Awesome Extension",
  "long_description": "Detailed description with markdown support",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://your-website.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/username/repo"
  },
  "homepage": "https://example.com/extension",
  "documentation": "https://docs.example.com",
  "support": "https://github.com/username/repo/issues",
  "icon": "icon.png",
  "screenshots": ["screenshot1.png", "screenshot2.png"],
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description"
    }
  ],
  "prompts": [
    {
      "name": "prompt_name",
      "description": "Prompt description"
    }
  ]
}

服务器类型

Node.js 服务器

{
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Python 服务器

{
  "server": {
    "type": "python",
    "entry_point": "server/main.py",
    "mcp_config": {
      "command": "python",
      "args": ["${__dirname}/server/main.py"],
      "env": {
        "PYTHONPATH": "${__dirname}/lib"
      }
    }
  }
}

二进制服务器

{
  "server": {
    "type": "binary",
    "entry_point": "server/my-server",
    "mcp_config": {
      "command": "${__dirname}/server/my-server",
      "args": ["--config", "${__dirname}/config.json"]
    }
  }
}

用户配置

基本配置

{
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": true
    },
    "timeout": {
      "type": "number",
      "title": "Timeout (seconds)",
      "description": "Request timeout in seconds",
      "default": 30,
      "minimum": 1,
      "maximum": 300
    },
    "debug_mode": {
      "type": "boolean",
      "title": "Debug Mode",
      "description": "Enable debug logging",
      "default": false
    }
  }
}

配置类型

string - 字符串值
number - 数值
boolean - 布尔值
array - 数组
object - 对象

配置属性

title - 显示标题
description - 描述
default - 默认值
required - 是否必需
sensitive - 是否敏感（存储在密钥链中）
minimum/maximum - 数值范围
pattern - 字符串正则表达式

环境变量

系统变量

${HOME} - 用户主目录
${TEMP} - 临时目录
${TMPDIR} - 临时目录（macOS）
${USERPROFILE} - 用户配置文件目录（Windows）

扩展变量

${__dirname} - 扩展安装目录
${user_config.key} - 用户配置值

使用示例

{
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/server/index.js"],
    "env": {
      "API_KEY": "${user_config.api_key}",
      "LOG_DIR": "${HOME}/.claude/logs",
      "TEMP_DIR": "${TEMP}"
    }
  }
}

跨平台支持

平台特定配置

{
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "platforms": {
        "win32": {
          "command": "node.exe",
          "env": {
            "TEMP_DIR": "${TEMP}"
          }
        },
        "darwin": {
          "env": {
            "TEMP_DIR": "${TMPDIR}"
          }
        },
        "linux": {
          "env": {
            "TEMP_DIR": "/tmp"
          }
        }
      }
    }
  }
}

开发最佳实践

1. 错误处理

// server/index.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
const server = new Server({
  name: "my-extension",
  version: "1.0.0"
});
 
server.setRequestHandler('tools/call', async (request) => {
  try {
    // 工具逻辑
    const result = await performToolCall(request.params);
    return { content: [{ type: 'text', text: result }] };
  } catch (error) {
    console.error('Tool call failed:', error);
    return {
      content: [{ 
        type: 'text', 
        text: `Error: ${error.message}` 
      }],
      isError: true
    };
  }
});

2. 输入验证

function validateInput(params) {
  if (!params.tool_name) {
    throw new Error('tool_name is required');
  }
  if (!params.arguments) {
    throw new Error('arguments are required');
  }
  return true;
}

3. 日志记录

import { createLogger } from 'winston';
 
const logger = createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ 
      filename: `${process.env.HOME}/.claude/logs/my-extension.log` 
    })
  ]
});

4. 超时管理

function withTimeout(promise, timeoutMs) {
  return Promise.race([
    promise,
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Operation timeout')), timeoutMs)
    )
  ]);
}

打包和测试

1. 验证清单

mcpb validate

2. 打包扩展

mcpb pack

3. 本地测试

将 .mcpb 文件拖到 Claude Desktop 设置窗口
检查扩展信息显示是否正确
测试安装和配置流程
验证工具调用是否正常工作

调试技巧

1. 启用详细日志

{
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/server/index.js"],
    "env": {
      "DEBUG": "*",
      "LOG_LEVEL": "debug"
    }
  }
}

2. 检查扩展目录

# macOS
ls -la ~/Library/Application\ Support/Claude/Extensions/
 
# Windows
dir %APPDATA%\Claude\Extensions\

3. 查看日志

# macOS
tail -f ~/Library/Logs/Claude/my-extension.log
 
# Windows
type %APPDATA%\Claude\Logs\my-extension.log

发布和分发

1. 准备发布

确保代码经过充分测试
更新版本号
编写清晰的文档
准备图标和截图

2. 提交审核

访问 Anthropic 扩展提交页面
上传 .mcpb 文件
填写扩展信息
等待审核结果

3. 维护更新

定期更新依赖
修复 bug 和安全问题
添加新功能
保持向后兼容性

CloudObsidian

Explorer

MCPB开发指南

MCPB 开发指南

什么是 MCPB？

文件扩展名更新

开发环境设置

1. 安装 MCPB 工具

2. 初始化项目

项目结构

Manifest 配置详解

必需字段

可选字段

服务器类型

Node.js 服务器

Python 服务器

二进制服务器

用户配置

基本配置

配置类型

配置属性

环境变量

系统变量

扩展变量

使用示例

跨平台支持

平台特定配置

开发最佳实践

1. 错误处理

2. 输入验证

3. 日志记录

4. 超时管理

打包和测试

1. 验证清单

2. 打包扩展

3. 本地测试

调试技巧

1. 启用详细日志

2. 检查扩展目录

3. 查看日志

发布和分发

1. 准备发布

2. 提交审核

3. 维护更新

相关资源

标签

Graph View

Table of Contents

Backlinks