GitHub Stars Contrib MCP Server

GitHub Stars贡献MCP服务器

GitHub Stars程序的模型上下文协议（MCP）服务器： .

它提供了一个全面的API，通过Stars GraphQL API使用您的个人API令牌来管理贡献、链接和配置文件数据。

• 传输：FastMCP（SSE可流式传输http）
• 功能：对贡献和链接进行完整的CRUD操作，配置文件管理

配置

环境变量：

• STARS_API_TOKEN:GitHub STARS个人资料中显示的代币（贡献→ 令牌）
• LOGLEVEL：调试|信息|警告|错误|严重（默认值：信息）
• MCP_HOST：为SSE传输绑定主机（默认值：127.0.0.1）
• MCP_PORT：绑定端口（默认值：8766）
• MCP_PATH：路径（默认值：/MCP）
• MCP_TRANSPORT：传输选择（“stdio”|“http”|“可流式传输http”|”sse“）。默认值：stdio。
• VALIDATE_URLS:在突变之前启用轻量级URL HEAD验证（默认值：false）
• URL_VALIDATA_TIMEOUT_S：URL验证请求超时（默认值：3）
• URL_VALIDATA_TTL_S:URL验证结果的TTL缓存（秒）（默认值：3600）

工具

服务器提供以下MCP工具：

突变（写入操作）：

• 创建_分配：创建单一贡献
• create_贡献：在单个突变中创建一个或多个贡献
• update_贡献：更新一个或多个贡献
• 删除贡献：删除一项或多项捐款
• create_link：在GitHub Stars个人资料中创建链接
• update_link：更新GitHub Stars个人资料中的链接
• delete_link：从GitHub Stars个人资料中删除链接
• update_profile：更新用户的个人资料信息

查询（读取操作）：

• get_user：获取登录用户（没有被提名人数据的最小用户信息）
• get_stars：获取GitHub用户的公开个人资料星/贡献
• 搜索_贡献：过滤用户公开Stars个人资料中的贡献
• get_contributions_stats：获取贡献统计和分析（可按类型、月份、年份分组）
• 比较贡献：比较两个用户之间的贡献
• 出口_贡献：以JSON、CSV或Markdown格式导出贡献

所有工具都返回标准化的响应格式： { "success": boolean, "data": object | null, "error": string | null }

快速启动

1. 创建一个virtualenv并安装

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install -e .[dev]

1. 配置环境（从模板）

   cp env.template .env
   # edit .env and set STARS_API_TOKEN
   set -a; source .env; set +a

或者，直接导出变量：

   export STARS_API_TOKEN=""
   export LOG_LEVEL=INFO

1. 运行MCP服务器（流式HTTP）

   python -m github_stars_contrib_mcp.server
   # Binds to MCP_HOST (default 127.0.0.1) and MCP_PORT (default 8766), path /mcp

无MCP客户端的本地使用

您可以通过一个小的演示脚本在本地测试这些工具。首先，确保Stars API代币可用（导出或将其放入 .env 项目根目录下的文件为 STARS_API_TOKEN=...).

export STARS_API_TOKEN=stars_...your_token...

然后运行：

python scripts/demo.py get-user-data
python scripts/demo.py create-contributions --data '[{"title": "Test Contribution", "url": "https://example.com", "type": "BLOGPOST", "date": "2023-01-01T00:00:00Z"}]'

Makefile快捷方式（load.env，如果存在则激活venv）：

make run-env

工具合同定义见 src/github_stars_contrib_mcp/tools/ （真相的来源）。

枚举和别名

有关链接平台，请参阅 PlatformType 在 src/github_stars_contrib_mcp/models.py。这些工具还接受几个遗留别名，这些别名在内部由 normalize_platform 在 src/github_stars_contrib_mcp/utils/normalization.py （例如。， GITHUB → README, WEBSITE → OTHER).使用别名时，会记录一条警告以帮助迁移调用者。

测试

单元测试：

. .venv/bin/activate
pytest -q

所有测试，包括可选的活突变e2e：

# Create `.env.local` with at least STARS_API_TOKEN; set STARS_E2E_MUTATE=1 to enable mutation tests
make test-all

笔记：

• 如果您的令牌不公开被提名人数据，则测试可能会跳过读取/配置文件流（这是意料之中的）。
• 确保 LOG_LEVEL 是以下之一：调试、信息、警告、错误、严重。

功能和路线图

该项目包括在10个关键领域计划的全面改进：

• 安全与认证
• 错误处理系统
• 数据验证
• 性能优化
• 完整的文件
• CI/CD自动化
• 监测和可观察性
• 高级测试
• 高级功能
• 高级体系结构

看 docs/feats/README.md 了解详细的实施计划和分阶段推出策略。