使用说明

基本框架MCP服务器

一个统一的模型上下文协议（MCP）服务器，提供对Base Framework CLI工具和全面文档的访问。服务器可以在本地运行进行开发，也可以部署到云端进行远程访问。

🎯 概述

此MCP服务器提供对基本框架功能的完全访问：

🛠️ 3个MCP工具：CLI命令、框架文档和特定文档文件
📚 真实文档：直接从Base Framework标记文件读取
🔄 总是新鲜：文档更改时自动更新
🌐 双模式：本地stdio和远程HTTP/SSE部署
☁️ 云就绪：使用Caprover、Docker等轻松部署

🛠️ 可用工具

1. `base_cmd_context`

完整的CLI命令参考，包括所有字段类型、关系模式和实际示例。

2. `base_framework_docs`

全面的框架文档，包括架构、模式、WebSocket、存储等。

3. `base_doc_file`

按名称访问特定文档文件（例如。， websocket.md, auth.md, storage.md).

🚀 安装和部署

🏠 地方发展

1.从源头构建

# Clone and build
git clone <repository>
cd base_mcp
make build

# Test the server
./base-mcp --version

2.克劳德桌面集成

macOS：

# Edit Claude Desktop config
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

窗户：

notepad %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "base-framework": {
      "command": "/absolute/path/to/base-mcp/base-mcp",
      "args": [],
      "env": {}
    }
  }
}

3.风帆集成

配置Windsurf：

# macOS/Linux
code ~/.codeium/windsurf/mcp_config.json

# Windows
code %APPDATA%\.codeium\windsurf\mcp_config.json

配置：

{
  "mcpServers": {
    "base-framework": {
      "command": "/absolute/path/to/base-mcp/base-mcp"
    }
  }
}

☁️ 云部署

🚢 盖层部署（推荐）

设置Caprover CLI：

npm install -g caprover

使用脚本部署：

# Configure your Caprover URL
export CAPROVER_URL="your-caprover-instance.com"
export APP_URL="https://mcp.base.al"

# Run deployment
./deploy.sh

手动部署：

# Login to Caprover
caprover login

# Create and deploy app
caprover apps:create base-mcp
caprover deploy --appName base-mcp

# Enable HTTPS
caprover apps:ssl:enable base-mcp --letsencrypt

Claude桌面配置（远程）：

{
  "mcpServers": {
    "base-framework": {
      "url": "https://mcp.base.al/sse"
    }
  }
}

🐳 Docker部署

本地测试：

# Build and run with Docker Compose
docker-compose up -d

# Test the deployment
curl http://localhost:8080/sse

生产部署：

# Build image
docker build -t base-framework-mcp .

# Run container
docker run -d \
  --name base-mcp \
  -p 8080:8080 \
  -e PORT=8080 \
  -e BASE_URL=https://your-domain.com \
  base-framework-mcp

☁️ 其他云平台

Heroku：

# Create Heroku app
heroku create base-framework-mcp

# Set environment variables
heroku config:set PORT=80
heroku config:set BASE_URL=https://base-framework-mcp.herokuapp.com

# Deploy
git push heroku main

铁路：

# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway login
railway deploy

Fly.io：

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Initialize and deploy
fly apps create base-framework-mcp
fly deploy

DigitalOcean应用平台：

连接您的GitHub存储库
设置环境变量： PORT=8080
在git推送上自动部署

AWS/GCP/Azure：

将Docker镜像与容器服务结合使用
集 PORT 和 BASE_URL 环境变量
启用HTTPS/SSL证书

🌐 DNS和域设置

对于 mcp.base.al 或自定义域：

将DNS指向您的部署：
- Caprover：指向您的Caprover实例
- Heroku： CNAME 向 yourapp.herokuapp.com
- 其他：指向部署IP/URL
SSL配置：
- 大多数平台都提供自动SSL
- 对于自定义设置，请使用Let's Encrypt

🔧 配置

环境变量

变量	描述	默认值
`PORT`	服务器的HTTP端口	stdio模式
`BASE_URL`	服务器的公共URL	`http://localhost:PORT`
`ENABLE_DOCS`	启用文档路径	`true`

部署模式

不 PORT 环境：在stdio模式下运行（本地MCP）
随着 PORT 环境：使用以下命令运行统一HTTP服务器：
- /sse -MCP服务器发送事件端点
- / -使用指南和设置说明（如果 ENABLE_DOCS=true)
- /docs/ -文档浏览器和文件（如果 ENABLE_DOCS=true)
文档路径:
- 默认情况下启用 PORT 已设置
- 与MCP端点位于同一端口上
- 禁用 ENABLE_DOCS=false 用于生产部署

🧪 测试

局部测试

# Test version
./base-mcp --version

# Test MCP communication
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | ./base-mcp

# Test tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | ./base-mcp

# Test specific tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"base_doc_file","arguments":{"filename":"websocket.md"}}}' | ./base-mcp

远程测试

# Test unified server endpoints
curl https://mcp.base.al/sse     # MCP SSE endpoint
curl https://mcp.base.al/        # Usage guide
curl https://mcp.base.al/docs/   # Documentation browser

# Test locally with all features
PORT=8080 ./base-mcp &
curl http://localhost:8080/sse   # MCP endpoint
curl http://localhost:8080/      # Usage guide  
curl http://localhost:8080/docs/ # Documentation

# Test with docs disabled (production mode)
PORT=8080 ENABLE_DOCS=false ./base-mcp &
curl http://localhost:8080/sse   # Only MCP endpoint available
curl http://localhost:8080/      # Returns 404

📖 使用示例

在克劳德桌面

配置后，您可以询问Claude：

Show me how to generate a Base Framework module with relationships

What are all the field types available in Base Framework?

Explain the WebSocket system in Base Framework

How do I set up authentication in Base Framework?

API使用

CLI命令：

{
  "method": "tools/call",
  "params": {
    "name": "base_cmd_context",
    "arguments": {}
  }
}

框架架构：

{
  "method": "tools/call",
  "params": {
    "name": "base_framework_docs", 
    "arguments": {}
  }
}

具体文件：

{
  "method": "tools/call",
  "params": {
    "name": "base_doc_file",
    "arguments": {
      "filename": "websocket.md"
    }
  }
}

🛠️ 发展

构建命令

make build      # Build binary
make dev        # Development build with race detection
make test       # Run tests
make fmt        # Format code
make lint       # Lint code (requires golangci-lint)
make clean      # Clean build artifacts

文件结构

base_mcp/
├── main.go           # MCP server implementation
├── md/docs/          # Base Framework documentation
├── Dockerfile        # Container configuration
├── captain-definition # Caprover deployment config
├── docker-compose.yml # Local Docker setup
├── deploy.sh         # Caprover deployment script
└── README.md         # This file

🐛 故障排除

常见问题

本地MCP不工作：

确保配置中的绝对路径
检查文件权限： chmod +x base-mcp
配置更改后重新启动Claude Desktop/Windsurf

无法访问远程部署：

检查环境变量(PORT, BASE_URL)
验证DNS配置
检查SSL证书状态
查看部署日志

文档未加载：

确保 md/docs/ 目录包含在部署中
检查容器中的文件权限
验证是否存在标记文件

调试步骤

先在本地测试： ./base-mcp --version
检查配置语法： 验证JSON配置文件
审核日志： 检查部署平台日志
测试终点： 使用curl测试HTTP部署
验证工具： 使用回声命令测试MCP通信

🤝 贡献

分叉存储库
创建特征分支
通过测试进行更改
提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅基础框架许可证。

🌟 从本地开发到全球云部署，随时可用的基础框架MCP服务器！