Mobile MCP Server

移动MCP服务器

一个全面的移动开发代码生成平台，同时支持MCP（模型上下文协议）和REST API。为MAUI、Kotlin/Android、Swift/iOS和React Native应用程序生成生产就绪代码。

📖 这个服务器能做什么？

寻找能力？ 看 容量.md 获取所有可用代码生成任务的完整指南！

快速摘要：

• 🎯 4移动平台： MAUI、Kotlin/Android、Swift/iOS、React Native
• 🔐 身份验证流程： 电子邮件/密码、生物识别、OAuth、SSO
• 💾 数据库设置： SQLite、Room、带存储库的核心数据
• 📴 离线功能： 同步策略和冲突解决
• 🔌 双重访问： 用于AI助手的MCP协议+用于直接使用的REST API

🚀 特性

• MCP协议支持：全面实施AI助手的模型上下文协议
• REST API：用于直接集成的简单HTTP端点
• 多平台代码生成：支持4个主要移动平台
• 生产就绪代码：生成完整的工作组件
• Docker就绪：使用Docker和Docker Compose完成容器化
• 健康监测：内置健康检查和监控端点
• 综合文档：详细指南和示例

📋 先决条件

• 码头工人：Docker桌面或Docker引擎
• Docker Compose：用于编排（通常包含在Docker桌面中）
• Node.js 18+：用于当地发展（可选）

🛠️ 快速开始

使用Docker（推荐）

1. 克隆或下载此存储库

1. 运行批处理文件 （Windows）：

   run.bat

或者直接使用Docker Compose（Windows/Mac/Linux）：

   docker-compose up --build

1. 访问服务器:

- 健康检查：http://localhost:3000/health - 服务器信息：http://localhost:3000/mcp/info - MCP端点：http://localhost:3000/mcp

使用Node.js（开发）

1. 安装依赖项:

   npm install

1. 启动服务器:

   npm start

或者用于自动重新加载的开发：

   npm run dev

🔧 API终点

健康检查

GET /health

返回服务器运行状况和基本信息。

服务器信息

GET /mcp/info

返回详细的服务器功能和配置。

MCP协议端点

POST /mcp

MCP协议通信的主要端点。

MCP检查器代理端点

POST /proxy/mcp

专为MCP检查器兼容性而设计的代理端点。 通过以下方式支持身份验证令牌 X-Proxy-Token 或 X-MCP-Token 标题。

代理信息

GET /proxy/info

返回MCP Inspector的代理配置和功能。

🔗 MCP检查器连接

MCP检查器的连接URL：

选项1：直接HTTP（推荐）

• 统一资源定位符: http://localhost:3000/mcp
• 运输：使用JSON-RPC 2.0的HTTP POST

选项2：代理HTTP（用于MCP检查器兼容性）

• 统一资源定位符: http://localhost:3000/proxy/mcp
• 运输：使用JSON-RPC 2.0的HTTP POST
• 标头：可选 X-Proxy-Token 用于身份验证

选项3:WebSocket

• 统一资源定位符: ws://localhost:3000/mcp/ws
• 运输：使用JSON-RPC 2.0的WebSocket

MCP检查器设置步骤：

1. 启动服务器：运行 npm start 或 ./run.sh
2. 打开MCP检查器 在浏览器中
3. 选择连接方式:

- 对于HTTP：使用 http://localhost:3000/proxy/mcp - 对于WebSocket：使用 ws://localhost:3000/mcp/ws

1. 添加身份验证 （可选）：如果需要，请包括代理令牌
2. 测试连接：服务器应使用可用工具进行响应。支持完整的JSON-RPC 2.0协议。

服务器发送事件（SSE）

GET /mcp/sse

用于实时MCP通信的流式端点。

🔍 MCP检查器集成

此服务器与MCP Inspector兼容，可用于测试和调试。要连接，请执行以下操作：

1. 启动服务器: npm start 或 ./run.sh （macOS/Linux）或 run.bat （Windows）
2. 打开MCP检查器 在浏览器中
3. 使用HTTP传输连接:

- 服务器URL: http://localhost:3000/mcp - 运输：HTTP - 协议：JSON-RPC 2.0

MCP检查器连接示例

服务器支持所有标准MCP方法：

• initialize -初始化MCP会话
• tools/list -列出可用工具
• tools/call -调用特定工具
• initialized -初始化后的通知

手动测试命令：

# Initialize connection
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

# List tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

# Call echo tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello MCP!",
        "format": "uppercase",
        "timestamp": true
      }
    }
  }'

🛠️ 可用工具

回声工具

一个演示工具，用可选的格式回显输入。

参数：

• message （必填）：要回显的消息
• format （可选）：格式类型-“纯”、“大写”、“小写”、“反向”
• timestamp （可选）：包括时间戳（布尔值）

请求示例：

{
  "method": "tools/call",
  "params": {
    "name": "echo",
    "arguments": {
      "message": "Hello World!",
      "format": "uppercase",
      "timestamp": true
    }
  }
}

示例响应：

{
  "content": [
    {
      "type": "text",
      "text": "[2025-11-07T10:30:00.000Z] HELLO WORLD!"
    }
  ]
}

🐳 Docker配置

塑造形象

docker build -t mobile-mcp-server .

使用Docker Compose运行

# Start the server
docker-compose up

# Start in background
docker-compose up -d

# Stop the server
docker-compose down

# Rebuild and start
docker-compose up --build

环境变量

📁 项目结构

Mobile-MCP-Server/
├── src/
│   ├── index.js                    # Main hybrid server (MCP + REST)
│   └── generators/
│       ├── MAUILoginGenerator.js   # MAUI template-based generator
│       └── platforms/              # Platform-specific generators
│           ├── KotlinGenerator.js  # Android/Kotlin code generation
│           ├── SwiftGenerator.js   # iOS/Swift code generation
│           └── ReactNativeGenerator.js # React Native code generation
├── templates/
│   └── maui/                       # MAUI template files (.template files)
├── docs/
│   ├── ARCHITECTURE.md             # Complete architecture documentation
│   ├── DEVELOPER_GUIDE.md          # Step-by-step development guide
│   ├── CODE_TEMPLATES.md           # Copy-paste templates for new platforms
│   └── COMPREHENSIVE_API_TEST.md   # Full API testing results
├── logs/                           # Log files (created at runtime)
├── docker-compose.yml              # Docker Compose configuration
├── Dockerfile                      # Docker image configuration
├── package.json                    # Node.js dependencies and scripts
├── run.bat                         # Windows batch file to start Docker
├── .env.example                    # Environment variables example
├── .gitignore                      # Git ignore patterns
└── README.md                       # This file

🏗️ 建筑与开发

此服务器遵循 混合式体系结构 无缝支持MCP协议和REST API。添加新平台或功能时，请遵循我们既定的模式：

📖 基本文件

• docs/ARCHITECTURE.md -完整的架构概述和设计原则
• docs/DEVELOPER_GUIDE.md -带完整Flutter示例的分步指南
• docs/CODE_TEMPLATES.md -复制粘贴模板以实现快速开发
• docs/COMPRESENSIVE_API_TEST.md文件 -完整的测试结果和服务器状态

🔧 发展模式

• 发电机类别：按照标准接口生成特定于平台的代码
• 混合协议支持：单个代码库同时服务于MCP和REST协议
• 基于模板的生成：逻辑和输出之间的清晰分离
• 一致的API模式：标准化选项和响应格式

🚀 快速添加平台

按照中的分步指南进行操作 docs/DEVELOPER_GUIDE.md 添加Flutter、Xamarin等新平台。该指南包括完整的示例和复制粘贴模板。

🔒 安全特性

• Helmet.js：安全标头和保护
• 跨域资源共享：可配置的跨源资源共享
• 输入验证：请求的JSON模式验证
• 非root用户：Docker容器以非root用户身份运行
• 健康检查：内置容器健康监测

🚀 发展

添加新平台

有关添加新移动平台的详细说明，请参阅我们的综合文档：

1. docs/DEVELOPER_GUIDE.md -使用Flutter示例完成分步演练
2. docs/CODE_TEMPLATES.md -即用型模板，实现快速开发
3. docs/ARCHITECTURE.md -了解系统架构和模式

新平台快速入门

1. 在中创建生成器类 src/generators/platforms/
2. 将平台导入添加到主服务器
3. 注册MCP工具和处理程序
4. 添加REST API端点
5. 更新文档端点
6. 测试所有功能

看 docs/CODE_TEMPLATES.md 用于加速此过程的复制粘贴模板。

遗留工具添加（供参考）

传统的MCP工具添加模式（现在被我们基于平台的方法所取代）：

1. 定义工具 在 ListToolsRequestSchema 处理程序：

   {
     name: 'your-tool-name',
     description: 'Tool description',
     inputSchema: {
       // JSON schema for input validation
     }
   }

1. 实施该工具 在 CallToolRequestSchema 处理程序：

   if (name === 'your-tool-name') {
     // Tool implementation
     return {
       content: [
         {
           type: 'text',
           text: 'Tool response'
         }
       ]
     };
   }

可用脚本

• npm start：启动生产服务器
• npm run dev：使用自动重新加载启动开发服务器
• npm run docker:build：构建Docker镜像
• npm run docker:run：使用Docker Compose运行
• npm run docker:stop：停止Docker容器

🔍 测试

测试回声工具

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello MCP!",
        "format": "uppercase",
        "timestamp": true
      }
    }
  }'

列出可用工具

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/list"
  }'

🐛 故障排除

MCP检查器连接问题

1. 代理令牌错误:

- 先尝试不进行身份验证（开发模式） - 使用 X-Proxy-Token 标头（如果需要身份验证） - 检查浏览器控制台是否存在CORS错误

1. 连接被拒绝:

- 确保服务器在端口3000上运行 - 检查防火墙设置 - 验证URL格式（http://或ws://）

1. CORS错误:

- 服务器在CORS白名单中包括MCP检查器域 - 尝试不同的连接方法（HTTP与WebSocket）

Docker问题

1. 确保Docker正在运行：检查Docker桌面或 docker info
2. 端口冲突：在中更改端口 docker-compose.yml 如果取3000
3. 权限问题：确保Docker具有适当的权限

连接问题

1. 检查防火墙：确保端口3000未被堵塞
2. CORS错误：更新 ALLOWED_ORIGINS 环境变量
3. 健康检查：参观http://localhost:3000/health

日志

• Docker日志: docker-compose logs mobile-mcp-server
• 集装箱日志: docker logs mobile-mcp-server

📝 许可证

麻省理工学院许可证-请随时为您的项目使用此样板！

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

📞 支持

对于问题和疑问：

1. 检查上面的故障排除部分
2. 查看Docker和Node.js文档
3. 检查MCP协议规范

______________________________________________________________________

编码愉快！ 🎉