Agent8 的 MCP 服务器

一个实现了模型上下文协议 (MCP) 的服务器，用于支持 Agent8 SDK 的开发。使用 TypeScript 和 pnpm 开发，支持 stdio 和 SSE 传输。

功能

此 Agent8 MCP 服务器实现了以下 MCP 规范功能：

提示词 (Prompts)

• Agent8 SDK 的系统提示词: 通过 system-prompt-for-agent8-sdk 提示词模板，为 Agent8 SDK 的开发提供优化的指导方针。

工具 (Tools)

• 代码示例搜索: 使用 search_code_examples 工具，从向量数据库中检索相关的 Agent8 游戏开发代码示例。
• 游戏资源搜索: 使用 search_game_resources 工具，通过语义相似性匹配搜索游戏开发资源（精灵图、动画、声音等）。

安装

# 安装依赖
pnpm install

# 构建
pnpm build

使用 Docker

您可以使用多种方式通过 Docker 运行此应用程序：

选项 1：从 GitHub Container Registry 拉取 (推荐)

# 拉取最新镜像
docker pull ghcr.io/planetarium/mcp-agent8:latest

# 运行容器
docker run -p 3333:3333 --env-file .env ghcr.io/planetarium/mcp-agent8:latest

选项 2：本地构建

# 构建 Docker 镜像
docker build -t agent8-mcp-server .

# 使用环境变量运行容器
docker run -p 3333:3333 --env-file .env agent8-mcp-server

Docker 环境配置

在使用 Docker 运行时，有三种配置环境变量的方法：

1. 使用 --env-file (推荐):

   # 首先创建并配置您的 .env 文件
   cp .env.example .env
   nano .env
   
   # 使用 .env 文件运行
   docker run -p 3000:3000 --env-file .env agent8-mcp-server
   

2. 使用单独的 -e 标志:

   docker run -p 3000:3000 \
     -e SUPABASE_URL=your_supabase_url \
     -e SUPABASE_SERVICE_ROLE_KEY=your_service_role_key \
     -e OPENAI_API_KEY=your_openai_api_key \
     -e MCP_TRANSPORT=sse \
     -e PORT=3000 \
     -e LOG_LEVEL=info \
     agent8-mcp-server
   

3. 使用 Docker Compose (用于开发/生产环境设置):

   该项目包含一个预配置的 docker-compose.yml 文件，具有以下功能：

   • 从 .env 配置自动端口映射
   • 环境变量加载
   • 用于数据持久化的卷挂载
   • 容器自动重启策略
   • 健康检查配置

   要运行服务器：

   docker compose up
   

   要在分离模式下运行：

   docker compose up -d
   

必需的环境变量：

• SUPABASE_URL: 用于数据库连接的 Supabase URL
• SUPABASE_SERVICE_ROLE_KEY: 用于身份验证的 Supabase 服务角色密钥
• OPENAI_API_KEY: 用于 AI 功能的 OpenAI API 密钥

Dockerfile 使用多阶段构建过程来创建最小的生产镜像：

• 使用 Node.js 20 Alpine 作为基础镜像，以减小尺寸
• 分离构建和运行时依赖项
• 仅在最终镜像中包含必要的文件
• 默认情况下公开端口 3000

用法

命令行选项

# 查看帮助
pnpm start --help

# 查看版本信息
pnpm start --version

支持的选项：

• --debug: 启用调试模式
• --transport <type>: 传输类型 (stdio 或 sse)，默认值：stdio
• --port <number>: 用于 SSE 传输的端口，默认值：3000
• --log-destination <dest>: 日志目标 (stdout, stderr, file, none)
• --log-file <path>: 日志文件路径 (当 log-destination 为 file 时)
• --log-level <level>: 日志级别 (debug, info, warn, error)，默认值：info
• --env-file <path>: .env 文件的路径

使用环境变量

服务器支持通过环境变量进行配置，环境变量可以直接设置或通过 .env 文件设置。

1. 在项目根目录中创建一个 .env 文件（参考 .env.example）：

# 复制示例文件
cp .env.example .env

# 使用您的设置编辑 .env 文件
nano .env

2. 运行服务器（它将自动加载 .env 文件）：

pnpm start

3. 或者指定 .env 文件的自定义路径：

pnpm start --env-file=/path/to/custom/.env

配置优先级

服务器在确定配置值时使用以下优先级顺序：

1. 命令行参数（最高优先级）
2. 环境变量（来自 .env 文件或系统环境）
3. 默认值（最低优先级）

这允许您在 .env 文件中设置基线配置，并在需要时通过命令行参数覆盖特定设置。

支持的环境变量

变量	描述	默认值
MCP_TRANSPORT	传输类型 (stdio 或 sse)	stdio
PORT	用于 SSE 传输的端口	3000
LOG_LEVEL	日志级别 (debug, info, warn, error)	info
LOG_DESTINATION	日志目标 (stdout, stderr, file, none)	stderr (对于 stdio 传输), stdout (对于 sse 传输)
LOG_FILE	日志文件路径 (当 LOG_DESTINATION 为 file 时)	(无)
DEBUG	启用调试模式 (true/false)	false
SUPABASE_URL	用于数据库连接的 Supabase URL	(必需)
SUPABASE_SERVICE_ROLE_KEY	用于身份验证的 Supabase 服务角色密钥	(必需)
OPENAI_API_KEY	用于 AI 功能的 OpenAI API 密钥	(必需)

使用 Stdio 传输

# 构建并运行
pnpm build
pnpm start --transport=stdio

使用 SSE 传输

# 构建并运行 (默认端口: 3000)
pnpm build
pnpm start --transport=sse --port=3000

调试模式

# 在调试模式下运行
pnpm start --debug

可用的提示词

• systemprompt-agent8-sdk

客户端集成

与 Claude Desktop 一起使用

1. 将以下内容添加到 Claude Desktop 配置文件 (claude_desktop_config.json)：

{
  "mcpServers": {
    "Agent8": {
      "command": "npx",
      "args": ["--yes", "agent8-mcp-server"]
    }
  }
}

2. 重启 Claude Desktop

添加新的提示词

将新的提示词添加到 src/prompts/provider.ts 文件中的 registerSamplePrompts 方法。

许可证

MIT