AI导哈

VersionOne MCP服务器

一个简化的模型上下文协议（MCP）服务器，用于VersionOne API集成，使AI助手能够查询VersionOne中的故事、特性（史诗）及其详细信息，并提供结构化输出。

  • by Quantiser
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 quantiser/mcp-server

使用说明

版本一MCP服务器

一种简化的模型上下文协议（MCP）服务器，使用 FastMCP 用于版本一API集成。该服务器使AI助手能够通过结构化输出查询VersionOne中的故事、特征（史诗）及其详细信息。

特性

服务器提供了四种主要的结构化Pydantic模型工具：

  1. get_stories -从VersionOne获取故事列表
  2. get_story_tails -按ID获取特定故事的详细信息
  3. get_features -从VersionOne获取功能列表（Epics）
  4. get_feature_details -按ID获取特定功能的详细信息

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器
  • VersionOne访问令牌
  • 您的VersionOne实例URL

安装

  1. 安装uv（如果尚未安装）：
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 克隆或下载此项目：
cd versionone-mcp-server
  1. 使用uv安装依赖项：
uv sync
  1. 配置您的VersionOne凭据：
cp env-template.txt .env
  1. 编辑 .env 使用您的实际VersionOne详细信息：
# Your VersionOne base URL (e.g., https://www7.v1host.com/V1Instance)
VERSIONONE_BASE_URL=https://your-v1-host.com/YourInstance

# Your VersionOne access token (recommended)
VERSIONONE_ACCESS_TOKEN=your-access-token-here

获取VersionOne访问令牌

  1. 登录您的VersionOne实例
  2. 导航到您的个人资料设置
  3. 转到应用程序页面
  4. 创建新的访问令牌
  5. 将令牌复制到您的 .env 文件

配置

环境变量

  • VERSIONONE_BASE_URL：您的VersionOne实例URL（例如。， https://www7.v1host.com/V1Instance)
  • VERSIONONE_ACCESS_TOKEN：您的VersionOne访问令牌（推荐方法）

MCP配置

将此服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "versionone": {
      "command": "uv",
      "args": ["run", "server", "stdio"],
      "cwd": "/path/to/versionone-mcp-server",
      "env": {
        "VERSIONONE_BASE_URL": "https://your-v1-host.com/YourInstance",
        "VERSIONONE_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

用法

运行服务器

uv run server stdio

可用工具

1.get_stories

通过可选筛选从VersionOne获取故事列表。

参数：

  • filters （可选）：包含查询筛选器的对象
    • where：其中过滤条款（例如。， 'AssetState!="Dead"')
    • sel：逗号分隔的要选择的属性列表（例如。， 'Name,Number,Description')
    • sort：排序顺序（例如。， 'Name')
  • page_size （可选）：每页项目数（默认值：20）
  • page_start （可选）：起始页码（默认值：0）

例子：

{
  "name": "get_stories",
  "arguments": {
    "filters": {
      "where": "AssetState!=\"Dead\"",
      "sel": "Name,Number,Description,Status"
    },
    "page_size": 10
  }
}

2.获取库存详细信息

通过ID获取特定故事的详细信息。

参数：

  • story_id （必填）：故事的ID（例如。， "Story:1234")
  • attributes （可选）：要检索的特定属性列表

例子：

{
  "name": "get_story_details",
  "arguments": {
    "story_id": "Story:1234",
    "attributes": ["Name", "Description", "Status", "Owner"]
  }
}

3.获取特征

通过可选过滤从VersionOne获取功能列表（Epics）。

参数：

  • filters （可选）：包含查询筛选器的对象
    • where：用于过滤的Where子句
    • sel：以逗号分隔的要选择的属性列表
    • sort：排序顺序
  • page_size （可选）：每页项目数（默认值：20）
  • page_start （可选）：起始页码（默认值：0）

例子：

{
  "name": "get_features",
  "arguments": {
    "filters": {
      "where": "AssetState!=\"Dead\"",
      "sel": "Name,Number,Description,Status"
    }
  }
}

4.获取特性详细信息

通过ID获取特定功能的详细信息。

参数：

  • feature_id （必填）：特征/史诗的ID（例如。， "Epic:1234")
  • attributes （可选）：要检索的特定属性列表

例子：

{
  "name": "get_feature_details",
  "arguments": {
    "feature_id": "Epic:1234",
    "attributes": ["Name", "Description", "Status", "Owner"]
  }
}

版本一API参考

此MCP服务器构建在VersionOne REST API之上。有关以下内容的更多详细信息：

  • 资产类型及其关系
  • 用于过滤和选择的可用属性
  • 查询语法和筛选选项
  • 验证方法

请参阅官方版本一API文档，网址：https://versionone.github.io/api-docs/

常见资产类型

  • 故事：用户故事和待办事项
  • 史诗：功能和大型工作项
  • 缺陷：错误和问题
  • 任务：开发任务
  • 测试：测试用例
  • 范围：项目
  • 时间框：冲刺/迭代

共同的属性

  • Name：项目的标题/名称
  • Number：自动生成的号码（如S-1001）
  • Description：详细说明
  • Status：项目的当前状态
  • Owner：指定的团队成员
  • AssetState：资产状态（活动、已关闭等）
  • CreateDate：创建项目时
  • ChangeDate：上次修改项目的时间

错误处理

该服务器包括全面的错误处理功能，用于：

  • 网络连接问题
  • 身份验证失败
  • API请求无效
  • 参数缺失或格式错误

错误会被记录并以用户友好的格式返回。

发展

以开发模式运行

# Install development dependencies
uv sync --dev

# Run with debug logging
uv run server stdio

测试

您可以使用任何兼容MCP的客户端或通过使用VersionOne API直接运行单个函数来测试服务器。

安全

  • 尽可能始终使用访问令牌而不是用户名/密码
  • 确保您的访问令牌安全，并定期轮换
  • 使用环境变量进行敏感配置
  • 从不将凭据提交到版本控制

故障排除

常见问题

  1. “VersionOne客户端未初始化”

    • 检查您的环境变量是否设置正确
    • 验证您的VersionOne URL格式
    • 确保您的访问令牌有效

  2. 身份验证错误（401）

    • 验证您的访问令牌是否正确且未过期
    • 检查您的VersionOne URL是否正确
    • 尝试创建新的访问令牌

  3. 网络超时

    • 检查您的互联网连接
    • 验证VersionOne服务器是否可访问
    • 如果需要，尝试增加代码中的超时时间

调试

通过在服务器代码中设置日志级别来启用调试日志记录：

logging.basicConfig(level=logging.DEBUG)

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

本项目按原样提供，用于教育和发展目的。

支持

关于以下问题：

  • 此MCP服务器：在此存储库中创建问题
  • VersionOne API：请参阅VersionOne文档或支持
  • MCP协议：请参阅MCP规范文档

相关 MCP