MCP 服务器

Jama Connect MCP Server (Unofficial)

Jama Connect 软件的模型上下文协议服务器

t-j-thomas

开发者工具

访问服务器

README

Jama Connect MCP 服务器 (非官方)

本项目提供了一个模型上下文协议 (MCP) 服务器，该服务器公开只读工具，用于与 Jama Connect 实例进行交互。它充当官方 Jama Software py-jama-rest-client 库的 MCP 包装器。

免责声明： 这是一个第三方开源项目，与 Jama Software 没有任何官方关联或认可。

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

理念：本地执行与安全

此 MCP 服务器有意未发布为 PyPI 或其他索引上的软件包。此决定鼓励用户：

克隆/Fork 存储库： 直接获取代码。
检查代码： 准确了解服务器在运行之前所做的事情，尤其是在 API 交互和凭据处理方面。
根据需要进行调整： 修改代码以满足特定的企业要求或安全态势。

这种方法优先考虑安全意识和用户控制，而不是便利性，从而降低了安装可能未经验证的第三方软件包相关的风险。目前仅支持通过克隆存储库进行本地执行。

前提条件

Python： 3.12 或更高版本。
uv： Python 包安装程序和虚拟环境管理器。 (安装指南)
Git： 用于克隆存储库。

设置

克隆存储库：

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

安装依赖项： 导航到服务器目录，并使用 uv 创建虚拟环境并安装依赖项。
```
uv sync
```
这将安装所需的依赖项，包括如果您计划使用 AWS Parameter Store 获取凭据，则会安装 boto3。

配置

服务器需要环境变量才能使用 OAuth 2.0 连接到您的 Jama Connect 实例。可以直接提供凭据，也可以从 AWS Parameter Store 安全地获取凭据。

身份验证方法：

直接环境变量：
- 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 配置。
AWS Parameter Store（推荐用于安全）：
- 仅当 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 以使用内置的模拟客户端。服务器将返回预定义的示例数据。任何其他值（或省略该变量）都会禁用模拟模式。

设置环境变量：

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

您的终端会话 (export JAMA_URL=...)。
直接在 MCP 客户端的服务器配置中（请参见下文）。

运行服务器（独立）

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

# 确保您位于 jama-mcp-server 目录中
uv run python jama_mcp/server.py

使用 `test_mcp_client.py` 进行测试

此存储库包含一个测试客户端脚本 (test_mcp_client.py)，该脚本可用于通过 stdio 直接调用服务器的工具，主要用于调试或快速检查，尤其是在模拟模式下。

要运行测试客户端：

# 确保您位于 jama-mcp-server 目录中
# 此脚本会自动为它启动的服务器设置 JAMA_MOCK_MODE=true
uv run python test_mcp_client.py

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

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

配置您的 MCP 客户端（如 Cline、RooCode、Claude Desktop）以通过其设置（例如，mcp_settings.json）启动此服务器。

示例配置 (mcp_settings.json):

{
  "mcpServers": {
    "jama-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "jama_mcp/server.py"
      ],
      
      "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)。
Mock Mode 无法正常工作： 确保 JAMA_MOCK_MODE 环境变量设置为完全 true。