JinDaGe - xcode-mcp-server MCP Details

article

README

🚀 Xcode MCP 服务器使用说明

Xcode MCP 服务器是一个方便开发者进行 Xcode 项目相关操作的工具，它提供了安装配置、工具使用等一系列功能，帮助开发者更高效地开展工作。

🚀 快速开始

如果你想快速使用 Xcode MCP 服务器，可参考下面的步骤：

完成服务器的安装。
对服务器进行必要的配置。
注册并使用工具进行相应操作。

📦 安装指南

请按照以下步骤安装 Xcode MCP 服务器：

克隆仓库

git clone https://github.com/yourusername/xcode-mcp-server.git
cd xcode-mcp-server

安装依赖
```
npm install
```
启动服务器
```
npm start
```

默认情况下，服务器将在 localhost:3000 上运行。

🛠️ 配置指南

1. 配置允许目录

在项目根目录下创建一个 .env 文件：

ALLOWED_DIRS=/path/to/your/project/directory

2. 配置日志级别

编辑 src/server.ts 文件，设置日志级别：

const logger = Logger({
  level: 'info', // 可选值：'debug'、'info'、'warn'、'error'
})

💻 使用示例

基础用法

1. 注册工具

在 src/tools/ 目录下创建一个新的工具类别，并在其中注册工具：

// src/tools/build/index.ts
export const build = new Tool({
  name: 'build',
  description: 'Builds an Xcode project or workspace.',
  parameters: {
    // 定义参数 schema
  },
})

2. 使用工具

通过发送 HTTP 请求来调用工具：

curl -X POST http://localhost:3000/tools/build \
     -H "Content-Type: application/json" \
     -d '{"parameter": "value"}'

🔒 安全指南

1. 路径验证

所有文件操作都会限制在允许的目录内：

const path = await validatePathAgainstAllowedDirs(filePath);

2. 错误处理

工具执行时会捕获并记录错误信息：

try {
  // 执行工具逻辑
} catch (error) {
  logger.error(error.message);
}

⚠️ 使用注意事项

权限问题：请确保允许的目录有正确的访问权限。
日志管理：及时清理旧的日志文件以避免磁盘空间不足。
兼容性检查：确保服务器与你使用的 Xcode 版本兼容。

🎯 高级主题

1. 自定义工具分类

在 src/tools/ 目录下创建新的子目录，并在对应的 index.ts 文件中注册工具：

// src/tools/custom/index.ts
export const customTool = new Tool({
  name: 'custom',
  description: 'Custom Xcode operation.',
  parameters: {
    // 定义参数 schema
  },
})

2. 扩展日志记录

自定义日志格式和输出：

const logger = Logger({
  format: ({ level, message }: { level: string; message: string }) =>
    `${new Date().toISOString()} [${level.toUpperCase()}] ${message}`,
});

❓ 常见问题

Q1. 如何处理路径访问错误？

A: 检查并确保你尝试访问的路径在允许目录内。

Q2. 为什么构建失败？

A: 确保 Xcode 命令行工具已安装且版本正确。

Q3. 工具未被识别？

A: 验证工具名称是否正确，并确认已在 index.ts 文件中注册。

🤝 贡献指南

欢迎贡献！请按照以下步骤提交 Pull Request：

** Fork 仓库**
** 创建功能分支**（git checkout -b feature/amazing-feature）
** 提交更改**（git commit -m 'Add some amazing feature'）
** 推送到分支**（git push origin feature/amazing-feature）
** 提交 Pull Request**

开发指南

遵循现有的代码风格和组织结构。
使用 Zod 方案进行参数验证并添加详细的错误消息。
为新功能编写测试用例。
更新文档以反映你的更改。
确保与不同项目类型（标准、工作区、SPM）兼容。

添加新工具

要向服务器添加新的工具，请执行以下步骤：

确定合适的类别 在 src/tools/ 目录下。
使用现有模式实现工具 并进行 Zod 方案验证。
在该类别的 index.ts 文件中注册工具。
添加错误处理和具体错误消息。
更新文档以记录新工具。

📄 许可证

[在此处插入许可证信息]

如需进一步帮助，请参考我们的 FAQ 页面或联系支持团队。

xcode-mcp-server