Jama Connect MCP Server (Unofficial)

Jama Connect MCP 服务（非官方）

本项目提供一个 Model Context Protocol（MCP）服务，用于公开只读工具，以便与 Jama Connect 实例交互。它是基于官方 Jama Software py-jama-rest-client 库构建的 MCP 封装。

免责声明： 这是一个第三方开源项目，与 Jama Software 无官方关联，也未获其认可。

注意： 此服务目前仅支持只读操作。未来更新中可能会添加写入操作。

理念：本地执行与安全性

此 MCP 服务不会发布到 PyPI 或其他索引中。此决定旨在鼓励用户：

1. 克隆/分叉代码库： 直接获取代码。
2. 检查代码： 在运行之前，准确了解服务的行为，尤其是 API 交互和凭据处理方面。
3. 按需调整： 根据特定的企业需求或安全要求修改代码。

这种做法优先考虑安全意识和用户控制权，而非便利性，从而降低安装未经验证的第三方软件包所带来的风险。目前唯一受支持的方式是克隆代码库并在本地运行。

先决条件

从源代码构建

• Python： 版本 3.12 或更高。
• uv： Python 软件包安装程序和虚拟环境管理器。（安装指南）
• Git： 用于克隆代码库。
• Docker： 用于通过 Docker 运行

设置

Docker

1. 克隆代码库：

   git clone https://github.com/t-j-thomas/jama-mcp-server.git
   cd jama-mcp-server
   

2. 构建 Docker 镜像：

   sudo docker build -t jama-mcp-server .
   

   这将使用项目的 pyproject.tonl 和 uv.lock 配置构建 Docker 镜像

3. 由于 Jama Rest Client 仓库证书导致的构建问题：

   如果看到类似 certificate verification failed: CAFile 的错误，可以选择 将 https://github.com/jamasoftware-ps/py-jama-rest-client.git 仓库克隆到此目录，并取消注释

   # py-jama-rest-client = { path = "./py-jama-rest-client", editable = true }

   在 pyproject.toml 文件中的这一行，并注释掉

   py-jama-rest-client = { git = "https://github.com/jamasoftware-ps/py-jama-rest-client.git" }。

   然后，

   uv sync
   sudo docker build -t jama-mcp-server .
   

从源代码构建

1. 克隆代码库：

   git clone https://github.com/t-j-thomas/jama-mcp-server.git
   cd jama-mcp-server
   

2. 安装依赖项： 进入服务目录，并使用 uv 创建虚拟环境并安装依赖项。

   uv sync
   

   这会安装所需的依赖项，包括在计划使用 AWS Parameter Store 存储凭据时所需的 boto3。

配置

该服务需要环境变量，以便通过 OAuth 2.0 连接到你的 Jama Connect 实例。凭据可以直接提供，也可以从 AWS Parameter Store 安全获取。

身份验证方法：

1. 直接使用环境变量：

   • JAMA_URL（必需）：你的 Jama Connect 实例的基础 URL（例如，https://yourcompany.jamacloud.com）。
   • JAMA_CLIENT_ID（此方法必需）：你的 Jama API OAuth 客户端 ID。
   • JAMA_CLIENT_SECRET（此方法必需）：你的 Jama API OAuth 客户端密钥。
   • 如果同时设置了 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET，系统将直接使用它们，并忽略 AWS Parameter Store 配置。

2. AWS Parameter Store（Docker 不支持）：

   • 仅当环境中没有同时直接设置 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET 时，才会使用此方法。
   • JAMA_URL（必需）：你的 Jama Connect 实例的基础 URL。
   • JAMA_AWS_SECRET_PATH（此方法必需）：AWS Parameter Store 中包含 Jama 凭据的密钥的完整名称/路径。
     • 密钥值必须是具有以下结构的 JSON 字符串：{"client_id": "YOUR_JAMA_CLIENT_ID", "client_secret": "YOUR_JAMA_CLIENT_SECRET"}。
   • JAMA_AWS_PROFILE（可选）：用于向 AWS 进行身份验证的 AWS 命名配置文件。如果未设置，boto3 将使用默认凭据解析方式。你当前的 AWS 会话凭据必须有效（如果已过期，则需刷新）。
   • **注意：**使用此方法需要安装 boto3 库（uv sync 会处理此项），并且服务的执行环境需要具备适当的 AWS 权限，才能访问指定的 Parameter Store 密钥。

服务会先检查 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET。如果两者都存在，则会使用它们。否则，服务会检查 JAMA_AWS_SECRET_PATH，并尝试从 AWS 获取凭据。如果两种方法都无法提供所需凭据（且未启用 Mock Mode），服务将无法启动。

Mock Mode（可选）：

如需在不连接到实际 Jama 实例的情况下进行测试：

• JAMA_MOCK_MODE：设为 true 以使用内置模拟客户端。服务将返回预定义的示例数据。设置为其他值（或省略此变量）将禁用 Mock Mode。

设置环境变量：

在 MCP 客户端启动服务进程的环境中设置这些变量。可以在以下位置设置：

• 终端会话中（export JAMA_URL=...）。
• MCP 客户端的服务配置中（见下文）。

运行服务（独立运行）

你可以使用 uv 直接运行服务进行基本检查（确保已设置环境变量）：

# Ensure you are in the jama-mcp-server directory
uv run python -m jama_mcp_server.server

使用 test_mcp_client.py 进行测试

此仓库包含一个测试客户端脚本（test_mcp_client.py），可用于通过 stdio 直接调用服务的工具，主要用于调试或快速检查，尤其是在 Mock Mode 下。

运行测试客户端：

# Ensure you are in the jama-mcp-server directory
# This script automatically sets JAMA_MOCK_MODE=true for the server it launches
uv run python test_mcp_client.py

该脚本将启动服务，调用多个预定义工具（包括 Mock Mode 下的成功案例和预期失败案例），打印结果并提供摘要。你可以修改此脚本，以测试特定工具或场景。

与 MCP 客户端集成（本地执行）

在 MCP 客户端（如 Cline、RooCode、Claude Desktop）的设置中配置该客户端，以便启动此服务（例如，在 mcp_settings.json 中配置）。

Docker 配置示例（mcp_settings.json）：

{
  "mcpServers": {
    "jama-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "JAMA_URL", "-e", "JAMA_CLIENT_ID", "-e", "JAMA_CLIENT_SECRET", "-e", "JAMA_MOCK_MODE",
        "jama-mcp-server"
      ],
      "env": {
        "JAMA_URL": "https://your-jama-instance.com",
        "JAMA_CLIENT_ID": "your-client-id",
        "JAMA_CLIENT_SECRET": ""
      }
    },
  }
}

UV 配置示例（mcp_settings.json）：

{
  "mcpServers": {
    "jama-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "jama_mcp_server.server"
      ],
      
      "cwd": "/path/to/your/clone/jama-mcp-server",
      "env": {
        "JAMA_URL": "https://your.jama.instance.com",
        "JAMA_CLIENT_ID": "your_client_id",
        "JAMA_CLIENT_SECRET": "your_client_secret",
        "JAMA_AWS_SECRET_PATH": "/path/to/your/jama/secret",
        "JAMA_AWS_PROFILE": "your-aws-profile-name",
        "JAMA_MOCK_MODE": "false"
      }
    }
  }
}

要点：

• cwd 路径对于让 uv 找到项目上下文至关重要。
• 确保服务进程能够获取所需的 Jama 环境变量。

可用工具

此服务提供多种只读工具。连接后，请查看 MCP 客户端界面获取完整列表。示例包括 get_jama_projects、get_jama_item、get_jama_relationships 等。

许可证

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

贡献

欢迎贡献和反馈！请参阅 CONTRIBUTING.md 文件，了解相关指南。

故障排除

• 连接／身份验证错误：
  • 确认 JAMA_URL 设置正确。
  • 检查 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET 是否设置正确。这两个变量优先使用。
  • 如果未设置直接变量，请检查 AWS Parameter Store 配置：
    • 确认 JAMA_AWS_SECRET_PATH 设置正确。
    • 确保服务的执行环境有权限读取密钥（检查 IAM 角色／策略）。
    • 确认密钥值是有效的 JSON：{"client_id": "...", "client_secret": "..."}。
    • 检查 boto3 是否已正确安装（uv sync）。
    • 如果使用 JAMA_AWS_PROFILE，请确保配置文件存在且配置正确。
  • 如果两种方式都无法提供凭据，服务将无法启动（请检查日志）。
  • 检查 Jama Connect 中的 Jama API 客户端权限。
• **工具错误：**检查传递给工具的参数。有关详情，请查看服务日志（stderr）。
• **模拟模式无法正常工作：**确保 JAMA_MOCK_MODE 环境变量的值恰好为 true。