使用说明

Jama Connect MCP服务器（非官方）

此项目提供了一个模型上下文协议（MCP）服务器，该服务器公开了用于与Jama Connect实例交互的只读工具。它充当着MCP对官员的包装 Jama软件 py-jama-rest-client 图书馆。

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

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

哲学：本地执行与安全

此MCP服务器是 故意不发表 作为PyPI或其他索引上的包。这一决定鼓励用户：

克隆/分叉存储库： 直接获取代码。
检查代码： 在运行服务器之前，请确切了解服务器的操作，尤其是有关API交互和凭据处理的操作。
根据需要进行调整： 根据特定的企业要求或安全态势修改代码。

这种方法将安全意识和用户控制置于便利性之上，从而降低了与安装可能未经验证的第三方软件包相关的风险。通过克隆存储库进行本地执行是目前唯一受支持的方法。

先决条件

从源头构建

python 版本3.12或更高版本。
紫外线： Python包安装程序和虚拟环境管理器。 (安装指南)
Git： 用于克隆存储库。
码头工人 用于运行docker

设置

码头工人

克隆存储库：

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

Docker构建：
```
sudo docker build -t jama-mcp-server .
```
这将使用项目的pyproject.tonl&uv.lock配置构建docker镜像
对于因Jama Rest客户代表证书而导致的构建问题：

如果你看到一个错误，比如 certificate verification failed: CAFile，您可以选择克隆https://github.com/jamasoftware-ps/py-jama-rest-client.git将repo存储到此目录中，然后取消注释

# 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 .
```

从源头构建

克隆存储库：

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

安装依赖关系： 导航到服务器目录并使用 uv 创建虚拟环境并安装依赖项。
```
uv sync
```
这将安装所需的依赖项，包括 boto3 如果您计划使用AWS参数存储作为凭据。

配置

服务器需要环境变量才能使用以下命令连接到您的Jama connect实例 OAuth 2.0。凭据可以直接提供，也可以从AWS参数存储中安全获取。

身份验证方法：

直接环境变量：
- 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参数存储配置将被忽略。
AWS参数存储（Docker不支持）：
- 使用此方法 只有当 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET 是不两者都直接设置在环境中。
- JAMA_URL （必填）：您的Jama Connect实例的基本URL。
- JAMA_AWS_SECRET_PATH （此方法需要）：AWS参数存储中包含您的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权限。

服务器首先检查 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET。如果两者都存在，则使用它们。否则，它会检查 JAMA_AWS_SECRET_PATH 并尝试从AWS获取凭据。如果两种方法都不提供必要的凭据（并且模拟模式关闭），服务器将无法启动。

模拟模式（可选）：

对于不连接到实时Jama实例的测试：

JAMA_MOCK_MODE：设置为 true 使用内置的模拟客户端。服务器将返回预定义的示例数据。任何其他值（或省略变量）都会禁用模拟模式。

设置环境变量：

在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直接调用服务器的工具，主要用于调试或快速检查，尤其是在模拟模式下。

要运行测试客户端，请执行以下操作：

# 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

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

与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许可证获得许可。请参阅许可证文件以获取详细信息。

贡献

欢迎投稿和反馈！请查看贡献.md 文件指南。

故障排除

连接/身份验证错误：
- 验证 JAMA_URL 是正确的。
- 检查是否 JAMA_CLIENT_ID 和 JAMA_CLIENT_SECRET 设置正确。这些优先。
- 如果未设置直接变量，请检查AWS参数存储配置：
  - 验证 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.

使用说明

Jama Connect MCP服务器（非官方）

哲学：本地执行与安全

先决条件

从源头构建

设置

码头工人

从源头构建

配置

运行服务器（独立）

测试与 test_mcp_client.py

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

可用工具

许可证

贡献

故障排除

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器

测试与 `test_mcp_client.py`