STARWARCLOUD STARWAR.AI
返回市场
贾玛-MCP服务器

贾玛-MCP服务器

作者：t-j-thomas10 星标更新：2025-04-16
安装使用来源：spider==github.com

项目介绍

Jama Connect MCP Server (非官方)

该项目提供了一个模型上下文协议（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参数存储来存储凭证，则需要安装boto3。

配置

服务器需要环境变量来连接您的Jama Connect实例，使用OAuth 2.0。凭证可以直接提供或从AWS参数存储中安全地获取。

认证方法：

  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参数存储配置。

  2. AWS参数存储（不支持Docker）：

    • 此方法仅在JAMA_CLIENT_ID和JAMA_CLIENT_SECRET未直接设置在环境中时使用。
    • JAMA_URL（必需）：您的Jama Connect实例的基本URL。
    • JAMA_AWS_SECRET_PATH（如果使用此方法则必需）：包含您的Jama凭证的AWS参数存储中的完整名称/路径。
      • 密钥值必须是一个具有以下结构的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客户端的服务器配置中（见下文）。

运行服务器（独立）

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

# 确保您在jama-mcp-server目录中
uv run python -m jama_mcp_server.server

使用test_mcp_client.py进行测试

此仓库包含一个测试客户端脚本（test_mcp_client.py），可用于直接通过标准I/O调用服务器的工具，主要用于调试或快速检查，特别是在模拟模式下。

要运行测试客户端：

# 确保您在jama-mcp-server目录中
# 此脚本自动将JAMA_MOCK_MODE设置为true，以便启动的服务器
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配置（m_cpc_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参数存储配置：
      • 验证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。