Skip to main content
Glama
deenesjakoruzh
jersonmartinez

github-project-management

by jersonmartinez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

GitHub Project Management MCP Server

MCP CI

自定义 MCP（模型上下文协议）服务器，使 AI 助手能够通过模型上下文协议以编程方式管理 GitHub Project V2 看板。使用 Python 3.12 和 FastMCP 构建，通过 stdio 传输通信，并在独立的 Docker 容器中运行。

位置

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

注意：此 MCP 服务器是独立组件，拥有自己的 Dockerfile、依赖项和生命周期。

Related MCP server: GitHub Projects MCP Server

工作原理

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

  1. MCP 客户端调用工具（例如：create_project_item）

  2. 执行 docker run --rm -i github-project-mcp:latest python server.py

  3. 服务器验证身份验证并等待 stdin 上的命令

  4. 客户端通过 stdin 发送 JSON-RPC，通过 stdout 接收响应

  5. 完成后，容器自动销毁（--rm）

Docker — 构建与管理

构建镜像

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose（本地开发）

在本地配置和运行 MCP 的最简单方式：

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile 目标

所有目标都在 Docker 内执行 — 无需主机依赖。

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

注意： 如果主机上没有 make，可以直接使用 Docker 调用目标。例如：docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

每位贡献者克隆仓库、创建自己的 .env，只需安装 Docker 即可使用 MCP。

验证镜像存在

docker images | grep github-project-mcp

手动测试（冒烟测试）

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

服务器将在 stderr 上打印：github-project-management MCP server ready. Authentication validated successfully. 然后等待 stdin 上的 JSON-RPC。按 Ctrl+C 退出。

修改后重建

docker build -t github-project-mcp:latest ./mcp --no-cache

管理脚本

脚本 ./scripts/dev/start.sh 支持 mcp 参数来管理镜像：

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

注意：MCP 不是持久化服务。不需要 up/down/restart。每次客户端使用工具时按需启动。

IDE 集成

MCP 兼容任何支持基于 stdio 的 MCP 协议的客户端。 配置因 IDE 而异 — 通用模式为：

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

有关各 IDE 的具体配置，请参阅 docs/SETUP.md。

已注册工具（100）

核心操作

工具

描述

discover_ids

发现项目/字段 ID

list_project_items

使用过滤器列出项目项

create_project_item

创建 issue 并添加到项目

update_project_item_fields

更新状态、优先级、截止日期

set_estimate

设置故事点估算

archive_project_item

从看板归档项目项

Issue 管理

工具

描述

close_issue

关闭 issue

reopen_issue

重新打开已关闭的 issue

comment_issue

向 issue 添加评论

edit_issue

编辑标题、正文、标签、里程碑、指派人员

add_sub_issue

链接为子 issue

remove_sub_issue

取消链接子 issue

get_issue_detail

获取完整的 issue 详情

search_issues

按查询条件搜索

看板操作

工具

描述

move_to_status

将项目项移动到任意状态列

move_to_done

标记为已完成

move_to_trash

移动到回收站

bulk_update_items

批量更新多个项目项

bulk_close_issues

批量关闭多个 issue

bulk_assign

批量指派多个 issue

规划与工作流

工具

描述

sprint_planning

生成冲刺计划

generate_release_notes

自动生成发布说明

complete_issue

完整完成工作流

daily_standup

生成每日站会报告

sprint_review

冲刺评审摘要

triage_new_issues

自动分类新提案

escalate_overdue

标记逾期项目项

create_epic

创建父项 + 子项

close_sprint

关闭冲刺并移动项目项

元数据

工具

描述

create_milestone

创建 GitHub 里程碑

close_milestone

关闭里程碑

list_milestones

列出里程碑

create_label

创建标签

list_labels

列出标签

get_project_stats

看板统计

get_sprint_summary

当前冲刺指标

架构

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

委派策略

方法

使用时机

gh CLI

Issue CRUD、评论、项目项添加、关闭

自定义 GraphQL

字段更新、归档、发现、子 issue

环境变量

变量

必需

描述

GITHUB_TOKEN

是

GitHub PAT（细粒度或经典）

GH_PROJECT_ORG_NAME

是

GitHub 所有者（组织或用户登录名）

GH_PROJECT_REPO_NAME

是

仓库名称

GH_PROJECT_PROJECT_NUMBER

是

Project V2 看板编号（1–100000）

故障排除

MCP 无法连接

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

重新连接 MCP

如果 MCP 与 IDE 断开连接，请使用相应 MCP 客户端的重新连接选项。

身份验证错误

  • 验证 GITHUB_TOKEN 在容器环境中可用

  • github_pat_*（细粒度）令牌需要权限：Issues（读写）、Projects（读写）、Metadata（读）

  • 经典令牌需要作用域：repo、project、read:org

相关文档

文档

用途

docs/SETUP.md

令牌设置和权限

docs/USAGE.md

工具输入/输出示例

docs/PARAMETERS.md

参数参考

docs/TROUBLESHOOTING.md

常见错误

源位置与同步

此目录（mcp/）是 MCP 包的规范真源。

仓库包含一个同步副本，位于：

  • app/backend/app/mcp/github_project/ — 嵌入后端用于 Docker 构建

同步工作流

  1. 首先在此处（mcp/）进行所有更改。

  2. 将修改的文件复制到嵌入路径：

    cp mcp/<file> app/backend/app/mcp/github_project/<file>

  3. 使用自动化检查验证：

    ./mcp/scripts/check_sync.sh

同步脚本比较所有共享的 .py 文件（排除 __init__.py，因为它在后端副本中有意不同，以及仅基础设施的文件，如 Dockerfile 和 requirements.txt）。CI 在每次推送时运行此检查 — 不一致会导致构建失败。

后端副本中有意不同的文件

文件

原因

__init__.py

后端特定的导入 + 同步源文档

README.md

指回此处；记录复制策略

后端测试套件对嵌入副本进行测试；语法验证必须编译两个目录树。

加固的运行时行为

所有设置使用 GH_PROJECT_ 前缀，并在启动时验证：

设置

默认值

边界 / 行为

GH_PROJECT_TIMEOUT_SECONDS

10

1–120 秒

GH_PROJECT_RETRY_ATTEMPTS

1

0–5；仅读取，变更操作永不重试

GH_PROJECT_RETRY_DELAY_SECONDS

2.0

0–60 秒，指数退避

GH_PROJECT_CACHE_TTL_HOURS

24

1–720 小时

GH_PROJECT_CACHE_PATH

.github_project_cache.json

可配置的本地路径

GH_PROJECT_PAGE_SIZE

100

1–100

GH_PROJECT_MAX_ITEMS

200

1–1,000

GH_PROJECT_MAX_CLI_OUTPUT_CHARS

1,000,000

10,000–10,000,000

元数据缓存以原子方式写入，使用仅所有者权限（0600），拒绝未来时间戳，并且在组织或项目编号不同时不重用。CLI 和 GraphQL 诊断会脱敏令牌类值，并在返回给 MCP 客户端之前进行限制。

仅 Docker 验证

无需主机 Python 工具即可运行验证：

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

本地验证（推送前）

在创建 PR 或推送更改之前始终运行。 这在本地镜像 CI 流水线，并在问题到达 GitHub Actions 之前捕获它们。

快速开始

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

检查内容

步骤

内容

与 CI 步骤相同

1. BOM

检测 Python 文件中的 UTF-8 BOM 字节

不适用（防止语法错误）

2. 构建

docker build -t github-project-mcp:validate ./mcp

"构建 MCP 镜像"

3. 语法

对镜像内所有 .py 文件执行 ast.parse

"语法检查"

4. 测试

运行 tests/ 中的测试模块

"运行单元测试"

5. 工具

统计已注册工具（必须 >= 100）

"验证工具数量"

6. 密钥

扫描跟踪文件中的令牌模式

不适用（发布前）

可用脚本

脚本

用途

使用时机

scripts/validate.sh

完整 CI 镜像

每次推送/PR 之前

scripts/preflight.sh

前置检查（Docker、令牌、配置）

首次设置或环境更改时

scripts/scan_secrets.sh

密钥模式检测

发布仓库之前

scripts/smoke_build.sh

最小构建 + 工具数量

快速健全性检查

scripts/run_contract_tests.sh

多目标契约套件

结构性更改之后

常见问题与修复

问题

症状

修复

BOM 字符

SyntaxError: invalid non-printable character U+FEFF

./mcp/scripts/validate.sh --fix

镜像未构建

Docker 命令中出现"Image not found"

docker build -t github-project-mcp:latest ./mcp

令牌未设置

预检中出现"No GitHub token found"

export GITHUB_TOKEN=ghp_...

工具数量 < 100

新工具未在 server.py 中注册

在 server.py 中添加 mcp.tool()(your_tool)

完整的 200 项清单（包括已实现和计划中的工作）位于 docs/HARDENING_200.md。

扩展能力套件：60 个附加工具

该服务器共暴露 100+ 个工具：原始 40 个操作工具加上来自 tools/capability_suite.py 的 60 个专项能力。

分组

用途

示例

Issue 与 Markdown 质量

验证、规范化、摘要、模板、打包和审查 issue

validate_issue_markdown、build_issue_template、build_issue_review_checklist

评论系统

创建进度、计划、阻塞和解决评论；列出/搜索/编辑评论

comment_issue_progress、comment_issue_blocker、list_issue_comments

项目报告

健康度、状态、优先级、负责人、截止日期和字段报告

project_health_report、project_due_date_risk、project_field_options_report

项目规划

导出/导入 Markdown、元数据同步计划和按筛选条件的批量计划

project_export_markdown、project_sync_issue_metadata、project_bulk_status_by_filter

战略自动化

冲刺计划、积压排序、风险/依赖报告和干系人更新

plan_next_sprint、prioritize_backlog、generate_risk_register

路线图与决策

变更日志、发布检查清单、路线图、回顾和自动化决策

generate_changelog_from_issues、build_roadmap_markdown、build_sprint_retrospective

可能造成大规模变更的工具默认返回 dry_run 计划。直接评论工具每次调用执行一次可见的评论操作。能力目录在导入时断言 60 个唯一新增项，Docker 验证确认两个源副本中均注册了 100 个 FastMCP 工具。

分发

Docker 镜像

MCP 服务器以独立 Docker 镜像形式分发。本地构建：

docker build -t github-project-mcp:latest ./mcp

CI/CD 流水线

mcp-ci.yaml 工作流在以下情况下自动运行：

  • 推送到 main 且 mcp/ 下的文件发生变更时

  • 涉及 mcp/ 路径的拉取请求

流水线阶段：

  1. 构建 — Docker 镜像构建验证

  2. 语法检查 — 对所有 Python 文件进行 AST 解析

  3. 单元测试 — 执行 pytest 测试套件

  4. 工具数量验证 — 确保注册的工具 ≥100 个

版本管理

此 MCP 服务器遵循语义化版本控制。发布历史请参阅 CHANGELOG.md。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers