Bmad Method MCP Server

BMAD-METHOD MCP服务器——多开发者网关

A. 远程MCP（模型上下文协议）服务器 和 多开发者网关 为了 BMAD方法 框架——通过Docker Compose在本地部署，并作为HTTP MCP服务器连接到Claude Code。

运作原理：服务器从中读取BMAD-METHOD资源文件（代理、工作流、任务、模板、检查表） bmad-method npm包安装在Docker容器中，并代理Neo4j、OpenMemory和RAG后端工具，因此开发人员只需要一个MCP连接，而不是五个。Claude Code通过HTTP连接到服务器，调用MCP工具加载代理角色，查询知识图，搜索内存，并执行语义搜索——然后AI在完全访问本地项目文件的情况下完成实际工作。没有GitHub API调用，没有速率限制，完全离线工作。

______________________________________________________________________

目录

• 架构概述
• 项目结构
• 先决条件
• 设置和部署
• Claude代码集成
• MCP工具参考
• MCP提示参考
• MCP资源参考
• BMAD-METHOD资源类型
• MCP服务器与本地安装——比较
• 源代码详解
• 配置参考
• 操作指南
• 故障排除
• 替代部署选项
• 学分

______________________________________________________________________

架构概述

┌─────────────────────────┐                        ┌──────────────────────────────┐
│     Claude Code CLI     │    MCP Protocol        │   Docker Container           │
│     (or any MCP client) │    (Streamable HTTP)   │   bmad-mcp-server v2.0.0    │
│                         │◄──────────────────────►│                              │
│  - Reads your project   │  POST/GET/DELETE       │   Node.js 22 (Alpine)        │
│  - Edits your files     │  /mcp/:developerId     │                              │
│  - Runs your tests      │  /mcp (anonymous)      │   ┌────────────────────────┐ │
│  - Executes commands    │                        │   │  Express + MCP SDK     │ │
│                         │                        │   │  (src/index.js)        │ │
│  Uses agent personas,   │                        │   │                        │ │
│  workflow guidance, and  │                        │   │  29 MCP Tools          │ │
│  backend tools returned  │                        │   │   7 BMAD content      │ │
│  by the server          │                        │   │  12 Neo4j (graph DB)   │ │
│                         │                        │   │   4 OpenMemory         │ │
│                         │                        │   │   6 RAG (vector)       │ │
│                         │                        │   │  3 MCP Prompts         │ │
│                         │                        │   │  Resource Templates    │ │
│                         │                        │   └────────┬───────────────┘ │
│                         │                        │            │                 │
│                         │                        │   ┌────────▼───────────────┐ │
│                         │                        │   │  bmad-method v6.0.0    │ │
│                         │                        │   │  npm package           │ │
│                         │                        │   └────────────────────────┘ │
│                         │                        │                              │
│                         │                        │   Health: GET /health        │
│                         │                        │   Port: 3001                 │
└─────────────────────────┘                        └──────────┬───────────────────┘
                                                              │ proxies to
                                                   ┌──────────┼──────────────┐
                                                   │          │              │
                                            ┌──────▼───┐ ┌───▼──────┐ ┌─────▼─────┐
                                            │ Neo4j DB │ │OpenMemory│ │  RAG API  │
                                            │  :7687   │ │  :8765   │ │  :8766    │
                                            └──────────┘ └──────────┘ └───────────┘

关键设计原则:

• MCP服务器返回 *指导和定义* BMAD内容。它不会执行任务、写入文件或访问您的项目。
• 后端工具（Neo4j、OpenMemory、RAG）有 代理的 通过网关，开发人员可以连接到单个MCP服务器，而不是五个。
• 后端工具包括 有条件的 --它们仅在配置了环境变量时注册。如果没有后端，该服务器将作为一个7工具BMAD内容服务器工作。
• 开发者身份 嵌入在URL路径中(/mcp/:developerId)用于HTTP模式或通过 BMAD_DEVELOPER_ID 一个是用于stdio模式。

______________________________________________________________________

项目结构

bmad-mcp-server/
├── docker-compose.yml        # Docker Compose service definition with backend env vars
├── Dockerfile                # Container image (Node 22 Alpine) with healthcheck
├── package.json              # v2.0.0 — deps: mcp-sdk, bmad-method, express, zod, neo4j-driver
├── package-lock.json         # Locked dependency versions
├── server.json               # MCP server manifest (schema v2025-10-17)
├── .gitignore                # Excludes node_modules, .env, *.log
├── README.md                 # This file
├── MULTI-DEVELOPER-GATEWAY-PLAN.md  # Implementation documentation
├── src/
│   ├── index.js              # Gateway entry point — 29 tools, identity, security, routing
│   ├── local-fetcher.js      # Filesystem reader for bmad-method npm package
│   ├── neo4j-client.js       # Neo4j driver wrapper (entity/observation/relationship model)
│   ├── openmemory-client.js  # OpenMemory HTTP client (native fetch)
│   └── rag-client.js         # RAG vector store HTTP client (native fetch)
├── custom/
│   └── phoenix-agent/        # Custom module (Phoenix agent definitions)
└── node_modules/
    ├── bmad-method/          # BMAD-METHOD v6.0.0-Beta.8 framework content
    ├── neo4j-driver/         # Neo4j Bolt driver v5.28.3
    ├── @modelcontextprotocol/sdk/  # MCP SDK v1.26+
    ├── express/              # Express v5.1
    └── zod/                  # Zod v4.3 schema validation

______________________________________________________________________

先决条件

• 码头工人 和 Docker Compose （v2+）
• 克劳德代码CLI （或任何兼容MCP的客户端）
• 端口 3001 在本地主机上可用
• *可选的*：用于后端集成的Neo4j数据库、OpenMemory API和/或RAG API

______________________________________________________________________

设置和部署

1.构建并启动容器

cd bmad-mcp-server
docker compose up -d

这个命令：

• 构建Docker镜像 Dockerfile （节点22阿尔卑斯山基地）
• 安装生产依赖关系(@modelcontextprotocol/sdk, bmad-method, express, zod, neo4j-driver)
• 副本 src/ 和 custom/ 放入集装箱
• 以HTTP传输模式启动端口3001上的MCP服务器
• 连接到已配置的后端（Neo4j、OpenMemory、RAG）
• 配置自动重启(unless-stopped)
• 允许每30秒进行一次健康检查

2.验证服务器是否正在运行

# Check container status
docker compose ps

# Test the health endpoint
curl http://localhost:3001/health

预期的健康反应：

{
  "status": "ok",
  "server": "bmad-method-mcp-server",
  "version": "2.0.0",
  "transport": "streamable-http",
  "activeSessions": 0,
  "sessionsByDeveloper": {},
  "backends": {
    "neo4j": "connected",
    "openmemory": "connected",
    "rag": "connected"
  }
}

将显示后端状态 "not configured" 如果没有设置相应的环境变量。

3.查看日志

docker compose logs -f

预期启动输出：

Neo4j client initialized: bolt://192.168.12.76:7687 (db: neo4j)
OpenMemory client initialized: http://192.168.12.76:8765
RAG client initialized: http://192.168.12.76:8766
BMAD-METHOD MCP Server (Gateway v2.0.0) running at http://0.0.0.0:3001/mcp
  Developer endpoint: http://0.0.0.0:3001/mcp/:developerId
  Health check:       http://0.0.0.0:3001/health
  Backends: Neo4j=yes, OpenMemory=yes, RAG=yes

______________________________________________________________________

Claude代码集成

注册MCP服务器

运行此命令以使用Claude Code注册BMAD MCP服务器，包括您的开发人员身份：

claude mcp add --transport http bmad http://localhost:3001/mcp/your.name

或者没有开发者身份（匿名）：

claude mcp add --transport http bmad http://localhost:3001/mcp

验证连接

claude mcp list

预期产量：

bmad: http://localhost:3001/mcp/your.name (HTTP) - ✓ Connected

Claude代码如何使用它

连接后，Claude Code可以自动访问所有BMAD工具和代理后端工具。当你使用斜线命令时，比如 /bmad-help 或 /bmad-bmm-dev-story克劳德代码：

1. 调用适当的MCP工具（例如。， bmad_activate_agent, bmad_get_workflow)
2. 接收代理角色、工作流定义、模板和检查表
3. 采用代理角色并遵循工作流指导
4. 可以查询Neo4j知识图，搜索OpenMemory，并执行RAG搜索
5. 使用本地项目上下文执行实际工作（编辑文件、运行命令）

卸下MCP服务器

claude mcp remove bmad

______________________________________________________________________

MCP工具参考

服务器最多可暴露 29工具 取决于配置了哪些后端。

BMAD内容工具（7个工具-始终可用）

bmad_get_file

按类型和名称获取任何BMAD-METHOD资源文件。

bmad_list_resources

列出资源类型下的所有可用文件。

bmad_activate_agent

加载具有可选依赖关系解析的完整BMAD代理定义。

bmad_search

在所有资源类型中搜索与关键字匹配的文件。

bmad_get_workflow

获取工作流定义，可选地包含所有支持文件。

bmad_help

获取有关BMAD-METHOD框架的帮助和指导。

bmad_clear_cache

在本地文件系统模式下没有操作。保留API兼容性。

______________________________________________________________________

Neo4j内存工具（9个工具-需要 NEO4J_URI + NEO4J_PASSWORD)

Neo4j密码工具（3个工具-需要 NEO4J_URI + NEO4J_PASSWORD)

OpenMemory工具（4个工具-需要 OPENMEMORY_URL)

所有OpenMemory工具都会自动作用于连接的开发人员的身份。

RAG工具（6个工具-需要 RAG_URL)

______________________________________________________________________

MCP提示参考

服务器为常见工作流显示3个MCP提示：

bmad-project-kickoff

在BMAD分析代理的指导下启动一个新项目。

bmad-activate

激活当前对话中的任何BMAD代理角色。

bmad-quick-spec

小功能或错误修复的快速规范流程。

______________________________________________________________________

MCP资源参考

使用资源URI直接访问BMAD文件 bmad:// 方案：

bmad://{type}/{name}

示例：

• bmad://agents/dev --开发代理定义
• bmad://templates/prd-template --PRD模板
• bmad://workflows/dev-story --开发故事工作流程

______________________________________________________________________

BMAD-METHOD资源类型

这 bmad-method npm包（v6.0.0-Beta.8）提供按以下类别组织的内容：

______________________________________________________________________

MCP服务器与本地安装——比较

BMAD-METHOD可以通过两种方式使用： MCP服务器 （Docker/HTTP）或通过 本地CLI安装程序 (npx bmad-method install).两者都提供相同的代理角色、工作流程、任务、模板和清单。AI行为和方法指导是相同的。不同之处在于内容的交付方式以及每个工具提供的额外工具。

并排

你应该使用哪一种？

______________________________________________________________________

源代码详解

src/index.js --网关入口点

目的：定义MCP服务器，注册所有29个工具/提示/资源，处理传输启动，并管理开发人员身份和安全。

关键部分：

1. 配置：读取传输、端口、主机、开发人员ID、安全设置和后端连接环境变量
2. 后端初始化：有条件地创造 Neo4jClient, OpenMemoryClient，以及 RagClient 基于环境变量
3. registerHandlers(srv, developerId)：在服务器实例上注册所有工具、资源和提示，范围为开发人员身份
4. BMAD内容工具 (7): bmad_get_file, bmad_list_resources, bmad_activate_agent, bmad_search, bmad_get_workflow, bmad_help, bmad_clear_cache
5. Neo4j内存工具 （9） ：实体、观察和关系CRUD操作
6. Neo4j密码工具 （3） ：原始读/写Cypher查询和模式自检
7. OpenMemory工具 （4） ：开发人员范围的内存存储和搜索
8. RAG工具 （6） ：语义搜索、混合搜索、索引和集合管理
9. 安全中间件：具有OPTIONS飞行前处理的可信主机验证和CORS
10. 会话管理：使用基于TTL的孤立会话清理进行每个开发人员会话跟踪
11. HTTP路由: /mcp/:developerId （已确定）和 /mcp （匿名，向后兼容）
12. 健康终点：服务器状态、开发人员的活动会话、后端连接状态
13. 平滑关闭：SIGINT/SIGTERM处理程序关闭Neo4j驱动程序连接

src/local-fetcher.js --文件系统读取器

目的：从中读取BMAD-METHOD内容 bmad-method npm包的本地文件系统。

关键设计决策：

1. 自动发现：解决 bmad-method 包裹位置通过 createRequire() 并导航到其 src/ 目录
2. 类型到目录映射：将逻辑资源类型映射到物理目录路径 bmm/, core/，以及 utility/ 目录
3. 延期决议：每种类型尝试多个扩展（例如，代理尝试 .agent.yaml, .yaml, .md)
4. 工作流捆绑包：返回工作流目录树中完整工作流上下文的所有文件

src/neo4j-client.js --Neo4j驱动程序包装器

目的：包裹 neo4j-driver 包，提供实体/观察/关系管理和原始Cypher执行。

关键设计决策：

• 实体模型: Entity 为节点添加标签 HAS_OBSERVATION 关系到 Observation 节点
• 关系: RELATES_TO 边缘与 relationType 属性（避免APOC依赖）
• 创意创作：用途 MERGE 用于实体创建
• Neo4j整数处理: _toPlain() helper将Neo4j整型转换为纯JS数字

src/openmemory-client.js --OpenMemory HTTP客户端

目的：使用本机的HTTP客户端 fetch() （节点22+）用于OpenMemory REST API。所有方法均接受 developerId 作为参数，由网关自动注入。

src/rag-client.js --RAG HTTP客户端

目的：使用本机的HTTP客户端 fetch() 用于RAG矢量存储API。提供语义搜索、混合搜索、文档索引和集合管理。

______________________________________________________________________

配置参考

环境变量

后端工具仅在设置了各自的环境变量时注册：

• Neo4j工具（12）：需要 NEO4J_URI + NEO4J_PASSWORD
• OpenMemory工具（4）：需要 OPENMEMORY_URL
• RAG工具（6）：需要 RAG_URL

Docker编写配置

services:
  bmad-mcp-server:
    build: .
    ports:
      - "3001:3001"
    environment:
      - BMAD_TRANSPORT=http
      - BMAD_PORT=3001
      - BMAD_HOST=0.0.0.0
      - BMAD_CUSTOM_PATHS=/app/custom
      # Neo4j backend
      - NEO4J_URI=bolt://192.168.12.76:7687
      - NEO4J_USERNAME=neo4j
      - NEO4J_PASSWORD=phoenix2026
      - NEO4J_DATABASE=neo4j
      # OpenMemory backend
      - OPENMEMORY_URL=http://192.168.12.76:8765
      # RAG backend
      - RAG_URL=http://192.168.12.76:8766
      # Security
      - BMAD_ALLOWED_HOSTS=localhost,127.0.0.1,192.168.12.76
    restart: unless-stopped

删除任何后端环境变量，以便在没有这些工具的情况下运行（例如，删除 NEO4J_URI 和 NEO4J_PASSWORD 禁用所有12个Neo4j工具）。

______________________________________________________________________

操作指南

启动服务器

docker compose up -d

停止服务器

docker compose down

重新启动（代码更改后）

docker compose up -d --build

完全重建（无缓存）

docker compose build --no-cache && docker compose up -d

查看日志

# Follow logs
docker compose logs -f

# Last 50 lines
docker compose logs --tail=50

检查健康状况

curl http://localhost:3001/health

健康终点报告：

• activeSessions --已连接的MCP客户端数量
• sessionsByDeveloper --每个开发人员身份的会话计数
• backends --Neo4j、OpenMemory和RAG的连接状态

更新BMAD-METHOD版本

# Update package.json version
npm update bmad-method

# Rebuild the container
docker compose up -d --build

开发模式（无Docker）

# Install dependencies
npm install

# Run with auto-restart on file changes
npm run dev

# Or run directly
BMAD_TRANSPORT=http node src/index.js

______________________________________________________________________

故障排除

容器显示“不健康”

检查日志：

docker compose logs --tail=20

10秒的启动期应留出初始化时间。如果持续存在，请验证端口3001：

curl -v http://localhost:3001/health

后端显示“未配置”

验证是否在中设置了相应的环境变量 docker-compose.yml对于Neo4j，两者 NEO4J_URI 和 NEO4J_PASSWORD 是必需的。

“找不到会话”错误

MCP会话是短暂的，存储在内存中。如果容器重新启动，所有会话都将丢失，客户端必须重新连接。Claude Code自动处理重新连接。持久状态存在于Neo4j和OpenMemory中。

DNS重新绑定警告

绑定到时，应出现有关DNS重新绑定保护的日志警告 0.0.0.0.配置 BMAD_ALLOWED_HOSTS 限制允许的主机。

工具列表返回错误

如果 tools/list 回报 Cannot read properties of undefined (reading '_zod')，这表明存在Zod模式兼容性问题。所有灵活的对象参数都必须使用 z.string() 随着 JSON.parse() 在处理程序中--不是 z.record(z.any()).

Claude Code看不到BMAD工具

验证MCP服务器是否已注册：

claude mcp list

如果未列出，请添加：

claude mcp add --transport http bmad http://localhost:3001/mcp/your.name

端口冲突

如果端口3001正在使用中，请在中更改端口映射 docker-compose.yml:

ports:
  - "3099:3001"   # Maps host port 3099 to container port 3001

然后更新克劳德代码注册：

claude mcp remove bmad
claude mcp add --transport http bmad http://localhost:3099/mcp/your.name

______________________________________________________________________

替代部署选项

stdio模式（直接，无Docker）

要在没有Docker的情况下进行更简单的设置，请在stdio模式下运行服务器：

BMAD_TRANSPORT=stdio BMAD_DEVELOPER_ID=your.name node src/index.js

在Claude Code注册为stdio MCP服务器：

claude mcp add bmad node /path/to/bmad-mcp-server/src/index.js -e BMAD_TRANSPORT=stdio -e BMAD_DEVELOPER_ID=your.name

HTTP模式（直接，无Docker）

BMAD_TRANSPORT=http BMAD_PORT=3001 node src/index.js

Docker（不含Compose）

docker build -t bmad-mcp-server .
docker run -d -p 3001:3001 \
  -e BMAD_TRANSPORT=http \
  -e NEO4J_URI=bolt://192.168.12.76:7687 \
  -e NEO4J_PASSWORD=phoenix2026 \
  -e OPENMEMORY_URL=http://192.168.12.76:8765 \
  -e RAG_URL=http://192.168.12.76:8766 \
  --name bmad-mcp bmad-mcp-server

______________________________________________________________________

学分

• BMAD方法 BMad Code（Brian Madison）——敏捷人工智能驱动的开发框架
• 模型上下文协议 Anthropic——实现人工智能工具集成的协议标准
• bmad-method npm包v6.0.0-Beta 8——内容源
• neo4j-driver v5.28.3--Neo4j Bolt协议驱动程序

许可证

麻省理工学院