工程生产力MCP服务器-混合架构

一套 专业工程分析MCP服务器 旨在与官方GitHub和Atlassian MCP服务器协同工作。这种混合方法通过官方服务器提供全面的平台功能，并通过定制分析服务器提供专门的工程生产力指标。

🏗️ 混合式结构

该项目现在遵循 混合式体系结构 它结合了：

官方MCP服务器（用于全面访问平台）：

****：存储库管理、问题、PR、工作流等
Atlassian的官方MCP服务器：确保对Jira和Confluence的OAuth访问安全

定制分析服务器（用于工程生产力洞察）：

GitHub分析：公关周期时间、审查指标、贡献分析
Jira分析：问题交付周期、解决方案跟踪、质量指标
汇流分析：文档生产力、内容参与度

特性

📊 GitHub工程分析

公关指标：创作率、合并统计、周期时间分析
复习活动：代码审查参与、评论参与
存储库筛选：将分析重点放在特定的存储库上
质量指标：合并率、审查参与率

📋 Jira工程分析

问题跟踪：分配率、解析速度、重新分析
交付周期计算：平均问题生命周期持续时间
质量指标：分辨率、缺陷分析
JQL过滤：基于自定义项目和标签的分析

📝 汇流工程分析

内容生产力：页面创建和更新率
参与度指标：评论活动、协作指标
空间分析：跨空间内容分发
文档速度：随时间推移的内容创作趋势

快速开始

1.先决条件

Python 3.10+
VS代码1.101+（用于远程MCP服务器）
Node.js 18+（适用于Atlassian服务器）
API访问GitHub、Jira和/或Confluence
虚拟环境（推荐）

2.安装

# Clone or navigate to project
cd engg-stats-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3.VS代码工作区设置（推荐）

此存储库包括一个完整的VS Code工作区配置，用于无缝开发：

# Open the workspace in VS Code
code engineering-stats-mcp.code-workspace

# Or open the folder directly
code .

这 .vscode/ 文件夹包含：

mcp.json：所有6台MCP服务器均已预配置
tasks.json：通过命令面板进行一键式服务器管理
launch.json：调试所有服务器的配置
settings.json：Python开发优化
extensions.json：推荐的扩展

快速VS代码设置：

开放的工作空间→ 出现提示时安装推荐的扩展
运行任务： Ctrl+Shift+P → “任务：运行任务”→ “安装依赖项”
运行任务：“启动所有主服务器”以启动GitHub/Jira/Confluence服务器
运行任务：“启动分析服务器”用于专用指标服务器

4.手动配置

# Copy environment template
cp .env.example .env

# Edit .env with your API credentials
nano .env

所需的环境变量：

# GitHub (for analytics server)
GITHUB_TOKEN=your_github_personal_access_token_here

# Jira (for analytics server)
JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your_jira_api_token_here

# Confluence (for analytics server)
CONFLUENCE_BASE_URL=https://your-org.atlassian.net/wiki
CONFLUENCE_EMAIL=your-email@company.com
CONFLUENCE_API_TOKEN=your_confluence_api_token_here

# Optional
LOG_LEVEL=INFO

4.设置混合MCP配置

选项1：使用预配置的设置

将混合配置复制到VS代码设置中：

cp vscode-mcp-hybrid-config.json ~/.config/vscode/mcp.json

选项2：手动配置

添加到您的VS Code MCP配置文件中：

{
  "mcp": {
    "servers": {
      "github-official": {
        "type": "http",
        "url": "https://api.githubcopilot.com/mcp/",
        "headers": {
          "Authorization": "Bearer ${input:github_mcp_pat}"
        }
      },
      "atlassian-official": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
      },
      "github-engineering-analytics": {
        "command": "python",
        "args": ["./mcp_github/analytics_server.py"],
        "cwd": "/path/to/engg-stats-mcp",
        "env": {
          "PATH": "/path/to/engg-stats-mcp/venv/bin:/usr/local/bin:/usr/bin:/bin"
        }
      },
      "jira-engineering-analytics": {
        "command": "python", 
        "args": ["./mcp_jira/analytics_server.py"],
        "cwd": "/path/to/engg-stats-mcp"
      },
      "confluence-engineering-analytics": {
        "command": "python",
        "args": ["./mcp_confluence/analytics_server.py"], 
        "cwd": "/path/to/engg-stats-mcp"
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "github_mcp_pat",
        "description": "GitHub Personal Access Token for Official MCP Server",
        "password": true
      }
    ]
  }
}

5.启动分析服务器

# Start all main servers (ports 4001-4003)
./start_all_servers.sh

# Start all analytics servers (ports 4011-4013)
./start_analytics_servers.sh

# Or start individual servers
./start_github_server.sh        # Port 4001
./start_jira_server.sh          # Port 4002
./start_confluence_server.sh    # Port 4003
./start_github_analytics.sh     # Port 4011
./start_jira_analytics.sh       # Port 4012
./start_confluence_analytics.sh # Port 4013

# Stop servers
./stop_all_servers.sh          # Stop main servers
./stop_analytics_servers.sh    # Stop analytics servers

服务器端口：

服务器	端口	类型
GitHub MCP	4001	主页
Jira MCP	4002	主
汇流MCP	4003	主
GitHub分析	4011	分析
Jira分析	4012	分析
汇流分析	4013	分析

6.完成设置

GitHub官方服务器：将使用OAuth或您配置的PAT
Atlassian官方服务器：首次连接时运行OAuth流
分析服务器：将自动使用环境变量

使用示例

GitHub分析

"Analyze GitHub engineering metrics for alice from 2025-11-01 to 2025-11-15 in the backend repos"

组合工作流

"First, get the open issues from project BACKEND (official server), then analyze alice's Jira productivity this month (analytics server)"

文档分析

"Show confluence activity for bob in the TECH space, plus create a summary page of his contributions (using both servers)"

技术架构

🏗️ FastMCP框架

所有自定义分析服务器都是使用 FastMCP 框架：

一致的实施：所有6台MCP服务器的标准化服务器模式
苏格兰和南方能源公司运输：服务器发送事件以进行实时通信
工具装饰器：简单的声明性工具定义
类型安全：用于输入验证和序列化的Pydantic模型

🛡️ 全面的错误处理

具有特定异常类型的强大错误管理系统：

分层误差系统：基地 MCPServerError 存在平台特定错误
API错误类型: GitHubAPIError, JiraAPIError, ConfluenceAPIError
验证错误：带有详细错误消息的输入验证
速率限制：具有指数回退的自动重试逻辑
网络弹性：超时处理和连接错误管理

🔌 VS代码集成

完整的开发环境配置：

MCP服务器配置：为所有6台服务器预先配置
调试支持：对所有服务器使用断点进行全面调试
任务自动化：通过命令面板进行一键式服务器管理
SHELL脚本：具有适当环境激活的替代启动脚本
故障排除：内置连接测试和错误诊断

架构优势

🔧 官方服务器提供：

强大的API访问：具有官方支持的完整平台功能
安全：OAuth 2.0身份验证、速率限制、安全更新
综合工具：完整的CRUD操作，高级功能
维护：由平台供应商自动更新和维护

📊 自定义分析提供：

专业指标：其他地方没有的工程生产力见解
自定义业务逻辑：根据您的特定需求量身定制计算
专注功能：轻量级、专门构建的分析工具
增强洞察力：对工程团队绩效进行更深入的分析

💡 综合效益：

无功能差距：完整的平台访问权限加上专门的分析
减少维护：官方服务器处理复杂的API管理
专注发展：自定义服务器只需要维护分析逻辑
两全其美：平台可靠性+定制见解

故障排除

VS代码MCP连接问题

“生成python ENOENT时出错”：VS Code找不到Python解释器。

解决方案：The .vscode/mcp.json 使用完整的虚拟环境路径
替代：使用基于shell的配置： cp .vscode/mcp-shell.json .vscode/mcp.json
测试：运行 python .vscode/test_mcp_connectivity.py 验证设置
重启：配置更改后重新启动VS代码

“正在等待服务器响应初始化请求”：服务器已启动但没有响应。

检查端口：终止端口4001-4003、4011-4013上的进程
终止命令: lsof -ti:4001,4002,4003,4011,4012,4013 | xargs kill -9
验证设置：运行 ./stop_all_servers.sh && ./stop_analytics_servers.sh 开始前
检查日志：查看VS代码输出面板→ MCP服务器日志

官方服务器

GitHub：关注
亚托西亚：关注 Atlassian MCP官方设置指南

分析服务器

速率限制：官方服务器自动处理API速率限制
认证：验证环境变量是否在中设置正确 .env
日志：检查服务器日志以获取具有错误类型的详细错误信息
测试：使用提供的测试脚本： test_startup.py, test_comprehensive.py

常见问题

端口冲突：主服务器使用4001-1003，分析使用4011-4013
环境变量：确保在中设置了所有必需的变量 .env
虚拟环境：在运行分析服务器之前，始终激活venv
Python路径：VS代码MCP配置使用 ${workspaceFolder}/venv/bin/python

迁移指南

如果从以前的独立实现升级：

安装官方服务器：遵循GitHub和Atlassian服务器的设置指南
更新配置：使用新的混合MCP配置
测试功能：验证官方服务器和分析服务器是否协同工作
删除旧脚本：老 start_all_servers.sh 被新的混合方法所取代

项目结构

engg-stats-mcp/
├── .vscode/                    # VS Code workspace configuration
│   ├── mcp.json               # MCP server configuration
│   ├── mcp-shell.json         # Alternative shell-based config
│   ├── tasks.json             # Task definitions for server management
│   ├── launch.json            # Debug configurations
│   ├── settings.json          # Python workspace settings
│   ├── start_*_mcp.sh         # Individual server startup scripts
│   └── test_mcp_connectivity.py # MCP setup validation
├── mcp_github/                 # GitHub MCP servers
│   ├── server.py              # Main GitHub MCP server (FastMCP)
│   └── analytics_server.py    # GitHub analytics server (FastMCP)
├── mcp_jira/                   # Jira MCP servers
│   ├── server.py              # Main Jira MCP server (FastMCP)
│   └── analytics_server.py    # Jira analytics server (FastMCP)
├── mcp_confluence/             # Confluence MCP servers
│   ├── server.py              # Main Confluence MCP server (FastMCP)
│   └── analytics_server.py    # Confluence analytics server (FastMCP)
├── shared/                     # Shared utilities
│   ├── errors.py              # Comprehensive error handling
│   ├── github_client.py       # GitHub API client with retry logic
│   ├── jira_client.py         # Jira API client with error handling
│   ├── confluence_client.py   # Confluence API client
│   └── date_utils.py          # Date/time utilities
├── test_startup.py             # Server startup validation
├── test_comprehensive.py       # Full functionality tests
├── test_vscode_config.py       # VS Code configuration tests
├── start_*.sh                  # Server startup scripts
├── stop_*.sh                   # Server shutdown scripts
├── engineering-stats-mcp.code-workspace  # VS Code workspace file
└── README.md                   # This file

测试

运行附带的测试套件以验证您的设置：

# Test server startup
python test_startup.py

# Test comprehensive functionality
python test_comprehensive.py

# Test VS Code configuration
python test_vscode_config.py

# Test MCP connectivity
python .vscode/test_mcp_connectivity.py

贡献

复刻仓库
将贡献集中在工程分析功能上
官方服务器问题应报告给各自的官方存储库
为新的分析功能添加测试
根据需要更新文档
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

工程分析工具

定制分析服务器提供了补充官方MCP服务器的专用工具：

GitHub工程分析

工具： `github_engineer_activity`

为GitHub用户计算全面的工程生产力指标。

输入:

{
  "login": "alice",
  "from_date": "2025-11-01", 
  "to_date": "2025-11-15",
  "repos": ["owner/repo1", "owner/repo2"]  // Optional
}

输出:

{
  "login": "alice",
  "from": "2025-11-01",
  "to": "2025-11-15",
  "repositories_analyzed": ["owner/repo1", "owner/repo2"],
  "metrics": {
    "pull_requests": {
      "authored": 12,
      "merged": 10,
      "merge_rate": 0.83
    },
    "cycle_times": {
      "average_hours": 48.5,
      "average_days": 2.0,
      "total_merged": 10
    },
    "code_review": {
      "reviews_given": 8,
      "comments_written": 23,
      "review_participation": 0.7
    }
  }
}

Jira工程分析

工具： `jira_engineer_activity`

分析用户的Jira问题活动和生产力指标。

输入:

{
  "user_email_or_account_id": "alice@company.com",
  "from_date": "2025-11-01",
  "to_date": "2025-11-15", 
  "jql_extra": "project = PROJ AND labels = backend"  // Optional
}

输出:

{
  "user": "alice@company.com",
  "from": "2025-11-01",
  "to": "2025-11-15",
  "jql_filter": "project = PROJ AND labels = backend",
  "metrics": {
    "issues": {
      "assigned": 15,
      "resolved": 12,
      "resolution_rate": 0.8,
      "reopened": 2,
      "quality_score": 0.83
    },
    "lead_times": {
      "average_hours": 72.3,
      "average_days": 3.0,
      "resolved_count": 12
    },
    "issue_distribution": {
      "types": {"Story": 8, "Bug": 4, "Task": 3},
      "priorities": {"High": 5, "Medium": 8, "Low": 2}
    }
  }
}

汇流工程分析

工具： `confluence_engineer_activity`

分析Confluence内容活动和文档生产力。

输入:

{
  "user_email_or_account_id": "alice@company.com",
  "from_date": "2025-11-01", 
  "to_date": "2025-11-15",
  "space_key": "TECH"  // Optional
}

输出:

{
  "user": "alice@company.com",
  "from": "2025-11-01",
  "to": "2025-11-15",
  "space_filter": "TECH",
  "period_days": 14,
  "metrics": {
    "content": {
      "pages_created": 3,
      "pages_updated": 7,
      "total_content_activity": 10,
      "creation_rate": 1.5,
      "update_rate": 3.5
    },
    "engagement": {
      "comments_written": 12,
      "comment_rate": 6.0,
      "engagement_ratio": 1.2
    },
    "distribution": {
      "spaces_active": 2,
      "spaces_breakdown": {"TECH": {"created": 2, "updated": 5}, "DOC": {"created": 1, "updated": 2}},
      "content_types": {"page": 3, "blog": 0}
    }
  }
}

IDE集成示例

一旦配置了混合设置，您就可以使用利用官方服务器和分析的自然语言提示：

基本操作（官方服务器）

*“显示后端项目中的未解决问题”* （Atlassian官员）
*“为登录错误创建新问题”* （Atlassian官员）
*“列出主分支中最近的提交”* （GitHub官方）
*“显示CI管道的工作流运行”* （GitHub官方）

工程分析（自定义服务器）

*“分析alice在2025-11-01到2025-15-15期间的GitHub活动”*
*“比较爱丽丝和鲍勃本月的Jira生产力”*
*“显示本季度团队的Confluence文档指标”*

组合工作流（两种服务器类型）

*“获取后端项目问题（官方），然后分析alice的解决方案指标（分析）”*
*“显示最近的PR（官方）并计算团队审核参与度（分析）”*
*“创建一份结合Jira问题数据（官方）和团队生产力指标（分析）的冲刺报告”*

API令牌设置

GitHub个人访问令牌

转到GitHub设置→ 开发人员设置→ 个人访问令牌
生成具有作用域的新令牌：

- repo （适用于私人回购）或 public_repo （仅供公众使用） - read:user - read:org （如果分析组织仓库）

Jira Cloud API代币

首选 id.atlassian.com
创建API令牌
使用您的Atlassian帐户电子邮件作为 JIRA_EMAIL

汇流云API代币

与Jira相同（可以重复使用相同的令牌和电子邮件）
确保您的帐户具有适当的空间权限

备注：对于官方Atlassian MCP服务器，OAuth 2.0身份验证是通过浏览器流自动处理的。

故障排除

常见问题

“超出费率限制”：API在速率受限时返回429个状态代码。服务器将返回可读的错误消息。请稍候，然后重试。

身份验证错误：在中验证您的API令牌和URL .env。检查令牌权限和过期时间。

导入错误：确保安装了所有依赖项： pip install -r requirements.txt

端口冲突：更改中的端口号 .env 如果使用默认值（4001-4003）。

调试

启用调试日志记录：

echo "LOG_LEVEL=DEBUG" >> .env

有关API请求/响应的详细信息，请查看服务器日志。

测试单个工具

直接通过curl测试工具：

# Test GitHub tool
curl -X POST http://localhost:4001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "github_engineer_activity",
      "arguments": {
        "login": "octocat",
        "from_date": "2025-11-01", 
        "to_date": "2025-11-15"
      }
    }
  }'

贡献

复刻仓库
为新工具或改进创建特征分支
添加新功能的测试
根据需要更新文档
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

Engg Stats MCP

快速接入

详细介绍

工程生产力MCP服务器-混合架构

🏗️ 混合式结构

官方MCP服务器（用于全面访问平台）：

定制分析服务器（用于工程生产力洞察）：

特性

📊 GitHub工程分析

📋 Jira工程分析

📝 汇流工程分析

快速开始

1.先决条件

2.安装

3.VS代码工作区设置（推荐）

4.手动配置

4.设置混合MCP配置

选项1：使用预配置的设置

选项2：手动配置

5.启动分析服务器

6.完成设置

使用示例

GitHub分析

组合工作流

文档分析

技术架构

🏗️ FastMCP框架

🛡️ 全面的错误处理

🔌 VS代码集成

架构优势

🔧 官方服务器提供：

📊 自定义分析提供：

💡 综合效益：

故障排除

VS代码MCP连接问题

官方服务器

分析服务器

常见问题

迁移指南

项目结构

测试

贡献

许可证

工程分析工具

GitHub工程分析

工具： github_engineer_activity

Jira工程分析

工具： jira_engineer_activity

汇流工程分析

工具： confluence_engineer_activity

IDE集成示例

基本操作（官方服务器）

工程分析（自定义服务器）

组合工作流（两种服务器类型）

API令牌设置

GitHub个人访问令牌

Jira Cloud API代币

汇流云API代币

故障排除

常见问题

调试

测试单个工具

贡献

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

工具： `github_engineer_activity`

工具： `jira_engineer_activity`

工具： `confluence_engineer_activity`