jama-cli

# Jama 命令行界面 [](https://github.com/XORwell/jama-cli/actions/workflows/ci.yml) [](https://pypi.org/project/jama-cli/) [](https://pypi.org/project/jama-cli/) [](https://ghcr.io/xorwell/jama-cli) 一个用于 Jama 需求管理的强大命令行界面，支持 MCP（模型上下文协议）服务器，用于 AI 助手。 > **免责声明**：这是一个非官方的社区项目，与 Jama Software 无关，也不得到其认可或支持。 ## 快速入门 ```bash # 安装 pip install jama-cli # 配置 jama config init # 使用 jama projects list jama items list 123 jama items get 456 --output json ``` ## 功能 ### 命令行命令 - **项目**：列出、查看和搜索项目 - **项目项**：完整的 CRUD 操作（创建、读取、更新、删除） - **关系**：管理上游/下游追踪 - **追踪性**：覆盖率分析、追踪矩阵、追踪树 - **基线**：比较基线、查看版本化项目项 - **历史记录**：查看项目项版本历史、比较版本 - **搜索**：跨项目进行全文和正则表达式搜索 - **差异**：比较项目、计算差异 - **迁移**：导出、导入、克隆、复制数据 - **类型**：查看项目项类型及其字段 - **配置**：多配置文件管理 > **参见 [EXAMPLES.md](https://github.com/XORwell/jama-cli/blob/main/EXAMPLES.md) 获取综合使用示例** ### MCP 服务器 - **stdio 模式**：与 Claude Desktop、Cline、VS Code 原生集成 - **HTTP 模式**：具有 OpenAPI 文档的 REST API - **70 个 Jama 操作**：完整的 API 覆盖 ### 输出格式 ```bash jama items list 123 # 表格（默认） jama items list 123 --output json # JSON jama items list 123 --output csv # CSV jama items list 123 --output yaml # YAML ``` ## 安装 ### pip（推荐） ```bash pip install jama-cli ``` ### pipx（隔离） ```bash pipx install jama-cli ``` ### 从源代码 ```bash git clone https://github.com/XORwell/jama-cli.git cd jama-cli pip install -e . ``` ## 配置 ### 交互式设置 ```bash jama config init ``` ### 配置文件 位置：`~/.jama/config.yml` ```yaml default_profile: production profiles: production: url: https://company.jamacloud.com auth_type: api_key api_key: ${JAMA_API_KEY} # 环境变量 staging: url: https://staging.jamacloud.com auth_type: oauth client_id: ${JAMA_CLIENT_ID} client_secret: ${JAMA_CLIENT_SECRET} defaults: output: table limit: 50 ``` ### 环境变量 ```bash export JAMA_URL=https://company.jamacloud.com export JAMA_API_KEY=your-api-key export JAMA_PROFILE=production # 可选：覆盖默认配置文件 ``` ## 命令行命令 ### 项目 ```bash jama projects list # 列出所有项目 jama projects get 123 # 获取项目详情 jama projects list --output json # JSON 输出 ``` ### 项目项 ```bash jama items list 123 # 列出项目 123 中的项目项 jama items get 456 # 获取项目项详情 jama items children 456 # 获取子项目项 # 创建项目项 jama items create 123 --type 45 --name "新需求" # 更新项目项 jama items update 456 --name "更新名称" jama items update 456 --field status=Approved # 删除项目项 jama items delete 456 jama items delete 456 --force # 跳过确认 ``` ### 关系 ```bash jama relationships list 456 # 项目项的所有关系 jama relationships upstream 456 # 上游项目项（追踪自） jama relationships downstream 456 # 下游项目项（追踪至） # 创建关系 jama relationships create --from 456 --to 789 # 删除关系 jama relationships delete 123 ``` ### 项目项类型 ```bash jama types list # 列出所有项目项类型 jama types get 45 # 获取类型详情 ``` ### 配置 ```bash jama config init # 交互式设置 jama config list # 列出配置文件 jama config show # 显示当前配置文件 jama config add prod --url https://... --api-key xxx jama config remove staging jama config set-default production jama config cache # 显示缓存统计信息 jama config cache --clear # 清除缓存 ``` ### 搜索 ```bash jama search items "login" # 搜索所有项目 jama search items "login" --project 123 # 在特定项目中搜索 jama search items "REQ-" --field documentKey # 按文档键搜索 jama search items "^REQ-\\d+" --regex # 正则表达式搜索 jama search items "test" --type 45 # 搜索特定项目项类型 jama search fields 123 # 列出可搜索字段 ``` ### 差异（比较项目） ```bash jama diff projects 123 456 # 比较两个项目 jama diff projects 123 456 --from dev --to prod # 跨实例比较 jama diff projects 123 456 --type 45 # 比较特定项目项类型 jama diff projects 123 456 --key name # 按名称匹配而不是按键 jama diff count 123 456 # 快速计数比较 ``` ### 追踪性分析 ```bash jama trace matrix 1172 # 追踪性矩阵 jama trace matrix 1172 -s 45 -t 67 # 需求 → 测试用例 jama trace matrix 1172 --untraced # 显示覆盖率空白 jama trace coverage 1172 # 按项目项类型显示覆盖率百分比 jama trace tree 12345 # 项目项的追踪树 jama trace tree 12345 --direction upstream # 仅上游 ``` ### 基线 ```bash jama baseline list 1172 # 列出基线 jama baseline items 100 # 基线中的项目项 jama baseline diff 100 101 # 比较基线 # 显示：+Added, ~Modified, -Removed ``` ### 版本历史记录 ```bash jama history list 12345 # 版本历史记录 jama history get 12345 3 # 获取版本 3 jama history diff 12345 1 3 # 比较版本 ``` ### 数据迁移 ```bash # 导出项目项到 JSON（默认快速） jama migrate export 123 # 导出所有项目项 jama migrate export 123 --max 100 # 导出前 100 个项目项（快速） jama migrate export 123 --parent 456 --max 50 # 导出子树，限制 50 jama migrate export 123 --type 45 # 仅导出类型 45 jama migrate export 123 --relationships # 包括关系（较慢） # 从 JSON 导入 jama migrate import backup.json --project 456 # 导入到项目 456 jama migrate import backup.json -p 456 --dry-run # 预览导入 # 在同一实例中克隆 jama migrate clone 123 456 # 克隆项目 123 到 456 jama migrate clone 123 456 --source-parent 789 # 克隆项目项的子项 # 在实例之间复制（需要两个配置文件） jama migrate copy 123 456 --from staging --to production # 检查导出文件 jama migrate info backup.json ``` ## MCP 服务器 ### 对于 Claude Desktop / Cline 将以下内容添加到您的 MCP 配置中： ```json { "mcpServers": { "jama": { "command": "jama", "args": ["serve", "--stdio"] } } } ``` ### HTTP 服务器 ```bash # 启动 HTTP 服务器 jama serve # 默认：localhost:8000 jama serve --port 9000 # 自定义端口 jama serve --api-key secret # 带有身份验证 # 访问 curl http://localhost:8000/health open http://localhost:8000/api/docs # Swagger UI ``` ### 可用操作 MCP 服务器公开了 70 个 Jama API 操作： | 类别 | 操作 | |----------|------------| | 项目 | get_projects, get_project | | 项目项 | get_items, get_item, create_item, update_item, delete_item | | 关系 | get_relationships, create_relationship, delete_relationship | | 类型 | get_item_types, get_item_type | | 选择列表 | get_pick_lists, get_pick_list, get_pick_list_options | | 标签 | get_tags, get_tagged_items | | 测试 | get_test_plans, get_test_cycles, get_test_runs | | 附件 | get_attachments, upload_attachment | | ... | 查看 API 文档中的完整列表 | ## 全局选项 ```bash jama [OPTIONS] COMMAND [ARGS] 选项： -p, --profile TEXT 配置文件名称 -o, --output FORMAT 输出：table, json, csv, yaml -v, --verbose 增加详细程度（-v, -vv, -vvv） -q, --quiet 禁止非错误输出 --version 显示版本 --help 显示帮助 ``` ## 示例 ### 列出需求并导出到 CSV ```bash jama items list 123 --type 45 --output csv > requirements.csv ``` ### 获取项目项为 JSON 以进行脚本编写 ```bash ITEM=$(jama items get 456 --output json) echo $ITEM | jq '.fields.name' ``` ### 从脚本创建项目项 ```bash jama items create 123 \ --type 45 \ --name "REQ-001: 用户身份验证" \ --description "用户应使用 SSO 进行身份验证" \ --field priority=High \ --field status=Draft ``` ### 追踪上游需求 ```bash jama relationships upstream 456 --output table ``` ### 使用不同的配置文件 ```bash jama -p staging items list 123 ``` ## Docker 预构建的 Docker 镜像可用于在不安装 Python 的情况下运行 Jama MCP 服务器。 ```bash docker pull ghcr.io/xorwell/jama-cli ``` ### 快速入门 ```bash # 使用环境变量 docker run -p 8000:8000 \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_API_KEY=your-api-key \ ghcr.io/xorwell/jama-cli ``` 服务器在端口 8000 上启动，带有健康检查、速率限制和 Swagger UI，位于 `/api/docs`。 ### 使用配置文件 将您现有的 `~/.jama/config.yml` 挂载到容器中： ```bash docker run -p 8000:8000 \ -v ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro \ ghcr.io/xorwell/jama-cli ``` 要使用配置文件中的特定配置文件： ```bash docker run -p 8000:8000 \ -v ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro \ ghcr.io/xorwell/jama-cli \ jama serve --host 0.0.0.0 --port 8000 --profile production ``` ### 身份验证方法 ```bash # API 密钥 docker run -p 8000:8000 \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_API_KEY=your-api-key \ ghcr.io/xorwell/jama-cli # OAuth2 客户端凭证 docker run -p 8000:8000 \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_CLIENT_ID=your-client-id \ -e JAMA_CLIENT_SECRET=your-client-secret \ ghcr.io/xorwell/jama-cli # 用户名/密码 docker run -p 8000:8000 \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_USERNAME=your-username \ -e JAMA_PASSWORD=your-password \ ghcr.io/xorwell/jama-cli ``` ### 服务器身份验证 使用 API 密钥保护 MCP 服务器，以便只有授权的客户端可以使用它： ```bash docker run -p 8000:8000 \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_API_KEY=your-jama-key \ -e MCP_API_KEY=my-server-secret \ ghcr.io/xorwell/jama-cli # 客户端必须包含：Authorization: Bearer my-server-secret ``` ### Docker Compose ```yaml services: jama-mcp: image: ghcr.io/xorwell/jama-cli ports: - "8000:8000" environment: - JAMA_URL=https://company.jamacloud.com - JAMA_API_KEY=${JAMA_API_KEY} # 或挂载配置文件： # volumes: # - ~/.jama/config.yml:/home/appuser/.jama/config.yml:ro restart: unless-stopped ``` ### 使用 Docker CLI 您还可以使用 Docker 镜像运行 CLI 命令： ```bash docker run --rm \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_API_KEY=your-api-key \ ghcr.io/xorwell/jama-cli \ jama projects list docker run --rm \ -e JAMA_URL=https://company.jamacloud.com \ -e JAMA_API_KEY=your-api-key \ ghcr.io/xorwell/jama-cli \ jama items list 123 --output json ``` ### 在本地构建 ```bash docker build -t jama-cli . docker run -p 8000:8000 -e JAMA_URL=... -e JAMA_API_KEY=... jama-cli ``` > **参见 [DOCKER.md](https://github.com/XORwell/jama-cli/blob/main/DOCKER.md) 获取完整的 Docker 文档**，包括端点、镜像详情、Kubernetes 探针等。 ## 开发 ```bash # 克隆 git clone https://github.com/XORwell/jama-cli.git cd jama-cli # 使用开发依赖项安装 poetry install # 运行测试 poetry run pytest # lint poetry run ruff check . poetry run black --check . # 类型检查 poetry run mypy jama_cli jama_mcp_server ``` ## 许可证 MIT 许可证 - 请参阅 [LICENSE](https://github.com/XORwell/jama-cli/blob/main/LICENSE) ## 贡献 欢迎贡献！请阅读 [CONTRIBUTING.md](https://github.com/XORwell/jama-cli/blob/main/CONTRIBUTING.md)。 ## 相关 - [Jama REST API 文档](https://dev.jamasoftware.com/api/) - [模型上下文协议](https://modelcontextprotocol.io/) - [py-jama-rest-client](https://github.com/jamasoftware-ps/py-jama-rest-client)