Devops Enhanced Mcp

开发 TypeScript

🚀 DevOps增强型MCP

这是一个动态的Azure DevOps MCP（模型上下文协议）服务器，它能够根据当前工作目录自动切换认证上下文。借助这个服务器，用户可以通过单个MCP服务器与多个Azure DevOps组织和项目实现无缝集成。

✨ 主要特性

本地配置文件：每个仓库都包含 .azure-devops.json 配置文件。
动态环境切换：根据目录位置自动检测项目上下文。
多项目支持：支持无限数量的项目，并为每个项目提供独立的认证。
全面的Azure DevOps集成：涵盖工作项、仓库、构建等功能。
零配置切换：通过本地配置文件，可在项目之间实现无缝切换。
安全的令牌存储：每个仓库将PAT令牌本地存储（不纳入git管理）。
错误处理与回退机制：具备强大的错误处理能力，在出现问题时可优雅地回退到环境变量。

📦 安装指南

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务器
npm start

💻 使用示例

基础用法

获取当前上下文

{
"name": "get-current-context",
"arguments": {
"directory": "/Users/wangkanai/Sources/riversync"
}
}

查询工作项

{
"name": "get-work-items",
"arguments": {
"wiql": "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active'"
}
}

创建工作项

{
"name": "create-work-item",
"arguments": {
"type": "Task",
"title": "Implement new feature",
"description": "Add authentication system",
"assignedTo": "user@example.com"
}
}

获取仓库列表

{
"name": "get-repositories",
"arguments": {
"includeLinks": true
}
}

📚 详细文档

本地配置

每个仓库都应包含一个 .azure-devops.json 配置文件：

配置文件结构

{
"organizationUrl": "https://dev.azure.com/your-org",
"project": "YourProject",
"pat": "your-pat-token-here",
"description": "Azure DevOps configuration for this repository",
"settings": {
"timeout": 30000,
"retries": 3,
"apiVersion": "7.1"
},
"tools": {
"workItems": true,
"repositories": true,
"builds": true,
"pullRequests": true,
"pipelines": true
},
"meta": {
"configVersion": "1.0",
"lastUpdated": "2025-07-21",
"createdBy": "devops-enhanced-mcp"
}
}

安全配置

重要提示：请将 .azure-devops.json 添加到你的 .gitignore 文件中：

# Azure DevOps MCP本地配置（包含PAT令牌）
.azure-devops.json

示例项目

RiverSync项目
- 目录：/Users/wangkanai/Sources/riversync
- 配置：包含RiverSync组织设置的 .azure-devops.json 文件。
Mula项目
- 目录：/Users/wangkanai/Sources/mula
- 配置：包含Mula组织设置的 .azure-devops.json 文件。

可用工具

工作项

get-work-items：使用WIQL查询或特定ID检索工作项。
create-work-item：创建新的工作项，可指定标题、描述、分配对象和标签。

仓库

get-repositories：列出当前项目上下文中的所有仓库。

构建

get-builds：获取构建定义和最近的构建历史记录。

上下文管理

get-current-context：根据目录获取当前的Azure DevOps上下文。

目录检测逻辑

服务器采用智能目录检测机制：

精确匹配：直接匹配配置的目录路径。
嵌套目录支持：可检测父项目目录。
最长匹配优先：最具体的目录匹配优先。
父目录搜索：在目录树中向上搜索匹配项。
回退配置：在未找到匹配项时使用默认配置。

认证

服务器使用个人访问令牌（PAT）进行Azure DevOps认证。PAT令牌在每个仓库的本地 .azure-devops.json 配置文件中按项目进行配置。

PAT令牌要求

PAT令牌应具备以下权限范围：

工作项：读写权限。
代码：只读权限。
构建：只读权限。
项目和团队：只读权限。

错误处理

服务器具备全面的错误处理功能：

配置错误：在配置缺失时进行优雅回退。
认证错误：认证失败时提供清晰的错误消息。
API错误：针对Azure DevOps API问题提供详细的错误报告。
网络错误：具备重试逻辑和超时处理。

测试与验证

增强验证系统（推荐）

增强验证系统包括MCP服务器启动、连接验证和就绪检查：

MCP服务器预热

# 准备MCP服务器进行验证
./warmup-mcp.sh

# 使用自定义配置文件
./warmup-mcp.sh custom-config.json

增强综合验证

# 进行包含MCP服务器初始化的全面验证
./validate-enhanced.sh

# 跳过交互式Claude测试（更快）
./validate-enhanced.sh --skip-interactive

# 为慢速系统进行扩展预热
./validate-enhanced.sh --warmup 20

# 仅测试特定仓库
./validate-enhanced.sh --repos "RiverSync,Mula"

# 使用自定义配置文件
./validate-enhanced.sh --config custom-config.json

# 显示所有选项
./validate-enhanced.sh --help

手动测试

# 手动构建并测试服务器
npm run build
node test-server.js

配置文件

通用验证系统使用 validation-config.json：

{
"proxyPath": "/Users/wangkanai/Sources/devops-enhanced-mcp",
"repositories": [
{
"name": "RiverSync",
"path": "/Users/wangkanai/Sources/riversync",
"expectedOrganization": "riversync",
"organizationUrl": "https://dev.azure.com/riversync",
"project": "RiverSync",
"enabled": true
}
],
"testSettings": {
"timeoutSeconds": 30,
"skipInteractive": false,
"mcpServerName": "devops-enhanced-mcp",
"configFileName": ".azure-devops.json"
},
"expectedTools": ["workItems", "repositories", "builds", "pullRequests", "pipelines"]
}

增强验证功能

增强验证系统包括：

🚀 MCP服务器管理
- 启动验证：确保MCP服务器配置正确。
- 连接测试：验证服务器连接性，具备重试逻辑。
- 就绪检查：确认服务器响应基本命令。
- 预热期：可配置服务器初始化延迟（默认：10秒）。
🔍 全面测试覆盖
- ✅ 先决条件：PowerShell、Claude Code、目录结构、代理构建。
- ✅ MCP初始化：服务器启动、连接性和就绪验证。
- ✅ 本地配置：验证 .azure-devops.json 文件是否包含预期值。
- ✅ 服务器配置：在不使用环境变量的情况下验证本地范围。
- ✅ Claude集成：执行MCP命令并检测上下文。
- ✅ 动态切换：在多个仓库之间进行环境切换。
- ✅ 错误处理：全面检测和报告错误，具备重试逻辑。

预期结果

全面验证结果：
- 通过率：成功实施时应大于90%。
- 两个仓库中的所有MCP命令均正常运行。
- 可根据目录位置自动切换上下文。

旧版环境配置（已弃用）

服务器以前支持使用全局 config/environments.json 文件进行环境映射。为了提高安全性和项目隔离性，此方法已弃用，建议使用本地 .azure-devops.json 配置文件。

如果需要从旧的基于环境的配置进行迁移，请将设置转换为每个仓库中的本地配置文件。

架构

核心组件

AzureDevOpsMCPProxy：处理MCP协议的主服务器类。
DirectoryDetector：智能目录检测和配置映射。
ToolHandlers：Azure DevOps API集成和工具实现。
ConfigLoader：配置文件加载和验证。

请求流程

工具调用接收：MCP客户端发送工具调用请求。
上下文检测：目录检测器识别当前项目上下文。
配置切换：服务器切换到适当的Azure DevOps配置。
API请求：工具处理程序向Azure DevOps发送经过认证的API请求。
响应处理：对响应进行格式化并返回给MCP客户端。

与Claude Code集成

此MCP服务器旨在与Claude Code无缝协作，用于Azure DevOps操作：

自动上下文切换：在RiverSync或Mula项目目录中工作时自动切换。
透明认证：无需手动配置。
丰富的工具集：提供全面的Azure DevOps功能。
错误恢复：优雅处理认证和网络问题。

安全考虑

PAT令牌存储在配置文件中（请确保设置正确的文件权限）。
所有Azure DevOps API通信均使用HTTPS。
每个请求都使用正确的令牌编码进行认证。
除配置文件外，不进行令牌缓存或持久化存储。

故障排除

常见问题

未找到配置文件：确保 .azure-devops.json 文件存在于项目目录中。
认证错误：验证PAT令牌的权限和有效期。
目录检测问题：检查项目中是否存在有效的 .azure-devops.json 文件。
API错误：验证本地配置中的Azure DevOps组织和项目名称。

调试模式

通过设置环境变量来启用调试日志：

export DEBUG=devops-enhanced-mcp
npm start

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

0 条评论
分类：开发