内容
# AtlasMind-Netra-mcp
AtlasMind-Netra-mcp 是 AtlasMind 平台的 AI 代理和 MCP 服务器层。它位于任何与 MCP 兼容的客户端（Claude Desktop、Cursor 或自定义 UI）和 `atlasMind-Lite` JQL 执行后端之间，在将任何查询发送到 Jira 之前运行多轮澄清循环。
Jira 查询由 LLM 编写，经常失败或返回错误结果，因为自然语言是模糊的 - “升级”可能是一个标签、自定义字段或优先级值；“今天”可能意味着创建、更新或今天到期；“我的团队”没有 JQL 等价。 该代理通过检测模糊术语、提出使用实时 Jira 实例中的真实字段名称的有针对性的澄清问题、学习团队约定，以便相同的问题永远不会被问两次，并且只有在意图完全解决后才调用 `atlasMind-Lite` 来解决这个问题。
公开暴露了五个 MCP 工具：`query_jira`、`generate_briefing`、`get_report`、`get_jira_context` 和 `search_context`。 所有其他内容 - 澄清循环、会话存储、意图分类器和约定存储 - 都是内部的。 所有五个工具都已完全连接：`query_jira` 运行澄清到调度循环；`generate_briefing` 将会议议程分解为主题、运行每个主题分析，并返回排名、引用简报，可选地用 Confluence 上下文丰富；`get_report` 通过 ID 获取存储的简报；`get_jira_context` 返回 Jira 实例元数据；`search_context` 通过 CQL 搜索 Confluence 并返回自然语言查询的排名页面摘录。 服务器已准备好进行云部署（可流式传输的 HTTP，`stateless_http=True`，有界内存缓存和可选的 Valkey 会话存储，用于水平扩展）。
## 前置条件
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) 用于依赖管理
- 一个 LLM API 密钥 - 选择一个：
- [Groq](https://console.groq.com/keys)（免费层，默认）：`GROQ_API_KEY`
- [Google AI Studio](https://aistudio.google.com/apikey)（免费层）：`GOOGLE_API_KEY`
- Anthropic、AWS Bedrock 或任何 OpenAI 兼容端点（参见下面的 [LLM 提供商](#llm-providers)）
- 可选的端到端运行：`http://localhost:8000` 上运行的 atlasMind 后端
- 可选的 Confluence 研究（`search_context` 工具和简报丰富）：具有 API 令牌身份验证的 Confluence Cloud 或 Data Center 实例
## 设置
```powershell
# 安装所有运行时和开发依赖项
uv sync
# 配置环境
copy .env.example .env
# 编辑 .env：设置您的 LLM API 密钥（GROQ_API_KEY 或 GOOGLE_API_KEY）和 NETRA_LLM__MODEL
```
所有设置都可以通过 `NETRA_*` 环境变量覆盖；有关完整列表，请参见 `.env.example`（后端 URL、LLM 模型、会话 TTL、澄清限制、传输）。
## LLM 提供商
所有五个 AI 代理（澄清器、议程分解器、问题分析器、查询意图分析器和上下文提取器）共享同一个 LLM，配置有两个环境变量：
| 提供商 | `NETRA_LLM__MODEL` | API 密钥环境变量 | 备注 |
| --- | --- | --- | --- |
| Groq（默认） | `groq:llama-3.3-70b-versatile` | `GROQ_API_KEY` | 免费层；快速 |
| Google Gemini | `google:gemini-2.0-flash` | `GOOGLE_API_KEY` | 免费层；在 aistudio.google.com 上获取密钥 |
| Google Gemini（替代） | `google:gemini-1.5-flash` | `GOOGLE_API_KEY` | 稳定的免费层替代品 |
| Anthropic | `anthropic:claude-haiku-4-5-20251001` | `ANTHROPIC_API_KEY` | 付费 |
| AWS Bedrock | `bedrock:anthropic.claude-sonnet-4-5` | AWS 凭证链 | IAM 角色或密钥对 |
| OpenAI 兼容 | `openai:<模型名称>` | `NETRA_LLM__API_KEY` 或 `OPENAI_API_KEY` | 设置 `NETRA_LLM__BASE_URL` 到提供商端点 |
Google Gemini 免费层示例 `.env`：
```
NETRA_LLM__MODEL=google:gemini-2.0-flash
GOOGLE_API_KEY=your_key_here
```
提供商根据模型字符串前缀自动检测 - 切换时无需其他代码更改。
## Confluence 研究
五个 MCP 工具中有两个支持 Confluence：
| 工具 | Confluence 角色 |
| --- | --- |
| `search_context` | 直接 Confluence 搜索 - 按主题、版本或关键词调查页面；支持通过 URL 固定特定页面 |
| `generate_briefing` | 在 Confluence 中研究每个议程主题（当配置时）并将找到的页面引用传递到问题分析中，在 Jira 评论旁边显示 Confluence 证据 |
两个工具都需要设置 `NETRA_CONFLUENCE__BASE_URL` 和 `NETRA_CONFLUENCE__API_TOKEN`。当它们未设置时，`search_context` 返回空结果，`generate_briefing` 在没有 Confluence 上下文的情况下运行 - 无错误，完全可选。
### 身份验证
| 身份验证类型 | 实例类型 | 需要设置的内容 |
| --- | --- | --- |
| 基本身份验证 | Confluence Cloud (`atlassian.net`) | `BASE_URL`（带有 `/wiki`）+ `EMAIL` + `API_TOKEN` |
| 承载令牌 | Confluence Server / Data Center | 仅 `BASE_URL`（无 `/wiki`）+ `API_TOKEN` |
云示例（`.env`）：
```
NETRA_CONFLUENCE__BASE_URL=https://yourorg.atlassian.net/wiki
NETRA_CONFLUENCE__EMAIL=you@yourorg.com
NETRA_CONFLUENCE__API_TOKEN=your_token_here
NETRA_CONFLUENCE__DEFAULT_SPACES=ENG,DOCS
```
服务器/DC 示例（`.env`）：
```
NETRA_CONFLUENCE__BASE_URL=https://confluence.internal
NETRA_CONFLUENCE__API_TOKEN=your_pat_here
NETRA_CONFLUENCE__DEFAULT_SPACES=ENG,DOCS
```
### 配置参考
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `NETRA_CONFLUENCE__BASE_URL` | 未设置 | Confluence 基本 URL。云：追加 `/wiki`。服务器/DC：根 URL，无 `/wiki`。 |
| `NETRA_CONFLUENCE__API_TOKEN` | 未设置 | API 令牌（云）或 PAT（服务器/DC）。在 id.atlassian.com/manage-profile/security/api-tokens 处创建。 |
| `NETRA_CONFLUENCE__EMAIL` | 未设置 | 仅限云 - 基本身份验证的帐户电子邮件。省略服务器/DC。 |
| `NETRA_CONFLUENCE__DEFAULT_SPACES` | （所有空间） | 用逗号分隔的空格键，例如 `ENG,OPS`。当未设置时，搜索所有空间。 |
| `NETRA_CONFLUENCE__SEARCH_LIMIT` | `10` | 每个 CQL 变体的最大返回页面。运行三个变体，然后重复。 |
| `NETRA_CONFLUENCE__MAX_PAGES_TOTAL` | `8` | 每个主题的最大处理页面（去重后）。限制总 LLM 提取调用。 |
| `NETRA_CONFLUENCE__CONFLUENCE_CONCURRENCY` | `3` | 每个主题的最大并发页面获取和 LLM 提取调用。 |
| `NETRA_CONFLUENCE__CONTENT_MAX_CHARS` | `10000` | 每个页面传递给 LLM 的章节文本的最大字符数。 |
| `NETRA_CONFLUENCE__PAGE_CACHE_TTL_SECONDS` | `300` | 原始 Confluence 页面 HTML 的缓存寿命，单位：秒。 |
| `NETRA_CONFLUENCE__RECENCY_DAYS` | `30` | CQL `lastModified` 过滤器的天数。 |
### `search_context` 工具参数
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `query` | `str` | 要研究的自然语言问题或主题。 |
| `spaces` | `list[str] \| None` | 此调用的空间键覆盖；优先于 `NETRA_CONFLUENCE__DEFAULT_SPACES`。 |
| `recency_days` | `int \| None` | `lastModified` CQL 过滤器的天数（默认：30）。传递 `null` 以删除最近限制。 |
| `limit` | `int` | 要返回的最大页面数（默认：5）。 |
| `page_urls` | `list[str] \| None` | 特定 Confluence 页面 URL，以固定在 CQL 搜索旁边。固定页面首先填充结果预算；当 `len(page_urls) >= limit` 时，CQL 搜索和意图分析 LLM 调用被完全跳过，节省一个 LLM 调用和三个 Confluence API 调用。支持云（`/pages/{id}/`）和服务器视图页面（`?pageId=`）URL 格式。URL 没有数字页面 ID 的报告错误并被宽容跳过。 |
| `force_refresh` | `bool` | 绕过所有缓存并从 Confluence 重新获取（默认：`false`）。当用户说结果已过时或错误时使用。 |
### 缓存和 `force_refresh`
`search_context` 和 `generate_briefing` 在三个级别缓存 Confluence 数据，以避免冗余的网络和 LLM 调用：
| 缓存 | 存储 | 生命周期 |
| --- | --- | --- |
| 页面 HTML（TTLCache） | 原始 Confluence 页面 HTML | `NETRA_CONFLUENCE__PAGE_CACHE_TTL_SECONDS`（默认 300 秒） |
| 提取（LRUCache） | 每个页面的 LLM 提取输出 | 由 LRU 淘汰 |
| 问题分析（FIFO 字典） | 每个问题的分析结果 | 最大 1000 条记录，FIFO 淘汰 |
传递 `force_refresh=true` 当用户报告数据已过时或不正确时。 调用跳过所有三个缓存读取，但仍将新结果写回缓存，以便下一次调用无需 `force_refresh` 即可从缓存中获取。 在 `generate_briefing` 上，`force_refresh` 传播到整个简报管道中的三个缓存。
## 如何测试 MCP 服务器
### 1. 运行自动化测试套件（无需网络，无需 API 密钥）
单元测试和集成测试模拟 LLM（PydanticAI `TestModel`）、后端 HTTP 调用（`httpx.MockTransport`）和 MCP 传输（内存 FastMCP 客户端），因此它们完全离线运行：
```powershell
uv run python -m pytest --cov=core --cov=memory --cov=models --cov=config
```
预期：所有测试通过，覆盖率远高于 85% 项目门控。
检查和类型检查（两者必须保持干净）：
```powershell
uv run ruff check .
uv run ruff format --check .
uv run mypy .
```
### 2. 使用 MCP 检查器进行交互式测试
最快的测试实时服务器的方法是 FastMCP 的开发检查器（打开浏览器 UI，您可以在其中列出工具并使用任意参数调用它们；需要 Node.js，因为检查器本身是一个 npm 包）：
```powershell
uv run fastmcp dev server.py:create_server
```
然后在检查器中：
1. 调用 `query_jira`，`query = "show escalations from today"` 和 `session_id = "test-1"`。
2. 预期响应 `requires_user_input: true` 和 `clarification_question`，引用标签/字段/优先级选项 - 即使没有后端或 Jira 实例，此操作有效。
3. 再次调用 `query_jira`，使用相同的 `query` 和 `session_id`，以及 `clarification_answer = "we use the escalation label"`。
4. 如果运行 atlasMind 后端，则获取 JQL + 问题；如果没有，则获取温和的 `errors: ["backend unreachable after retries: ..."]` 响应，这仍然证明澄清循环端到端。
5. 重复步骤 1，并使用新的 `session_id` - 这次没有问题：约定已学习并持久化到 `data/conventions.json`。
所有五个工具都是实时的。尝试 `generate_briefing`，使用 `agenda_text = "top blockers in project X, risks for carline Y"` 和 `session_id = "brief-1"`，以查看完整的简报管道。尝试 `search_context`，使用 `query = "release blockers for R1"`（需要设置 `NETRA_CONFLUENCE__BASE_URL`）。
### 3. 从 Claude Desktop（stdio）测试
将以下内容添加到 `claude_desktop_config.json`（设置 -> 开发者 -> 编辑配置）。
使用 Groq（默认）：
```json
{
"mcpServers": {
"atlasmind-netra": {
"command": "uv",
"args": [
"--directory",
"\\path\\to\\AtlasMind-Netra-mcp",
"run",
"python",
"server.py"
],
"env": {
"GROQ_API_KEY": "gsk_..."
}
}
}
}
```
使用 Google Gemini 免费层（替代）：
```json
{
"mcpServers": {
"atlasmind-netra": {
"command": "uv",
"args": [
"--directory",
"\\path\\to\\AtlasMind-Netra-mcp",
"run",
"python",
"server.py"
],
"env": {
"NETRA_LLM__MODEL": "google:gemini-2.0-flash",
"GOOGLE_API_KEY": "AIza..."
}
}
}
}
```
重启 Claude Desktop，然后询问：*“使用 atlasmind-netra 工具，显示今天的升级。”* Claude 应该将澄清问题原样中转给您（工具描述禁止它自己回答），再次调用工具并提供您的答案，并呈现结果。
### 4. 通过 streamable-http（生产传输）测试
在此模式下，服务器作为 Web 服务独立运行，客户端通过 HTTP 连接到它，而不是将其作为子进程生成（stdio）。一个服务器进程可以为多个用户提供服务；这是设计文档中的生产传输。
#### 终端 1 - 以 HTTP 模式启动服务器
```powershell
$env:NETRA_SERVER__TRANSPORT = "streamable-http"
uv run python server.py
```
（或在 `.env` 中设置 `NETRA_SERVER__TRANSPORT=streamable-http`。）`GROQ_API_KEY` 必须在此终端或 `.env` 中可用，因为澄清器 LLM 在服务器端运行。
`main()` 在 `server.py` 中读取设置并启动绑定到 `127.0.0.1:8765` 的 uvicorn。 FastMCP 的默认端点为 `streamable-http` 协议，因此客户端需要的完整 URL 为：
```
http://127.0.0.1:8765/mcp
```
要更改绑定地址或端口，请在启动前设置 `NETRA_SERVER__HOST` / `NETRA_SERVER__PORT`（例如，设置 `0.0.0.0` 以接受来自其他机器的连接）。让这个终端保持运行；下面所有操作都在第二个终端中进行。
#### 终端 2，选项 A - MCP 检查器
```powershell
npx @modelcontextprotocol/inspector
```
在打开的浏览器 UI 中：选择 **Streamable HTTP**，输入 `http://127.0.0.1:8765/mcp`，然后点击 **Connect**。您将获得与 stdio 开发模式相同的 UI - 列出五个工具并使用 JSON 参数调用 `query_jira`（参见第 2 节中的测试脚本）。
#### 终端 2，选项 B - Claude 代码
注册正在运行的服务器：
```powershell
claude mcp add --transport http atlasmind-netra http://127.0.0.1:8765/mcp
```
此命令告诉 Claude Code 将新的 MCP 服务器与 Claude Code 关联起来：
- `claude mcp add` - 在 Claude Code 中注册新的 MCP 服务器
- `--transport http` - 通过 HTTP 连接（服务器是单独的进程，而不是被 Claude 产生的子进程）
- `atlasmind-netra` - Claude Code 用于标识此服务器的名称
- `http://127.0.0.1:8765/mcp` - 服务器正在侦听的地址
您只需要运行一次此命令；Claude Code 会在会话之间记住注册。
然后启动一个 Claude Code 会话并询问，例如：*“使用 atlasmind-netra 工具，显示今天的升级。”* Claude 将中转澄清问题，再次调用工具，并呈现结果。删除注册后，使用 `claude mcp remove atlasmind-netra`。
#### 本模式的注意事项
- **会话存在于服务器进程中。** 第一阶段存储在内存中：挂起的澄清在服务器运行期间在工具调用之间存活，但服务器重启后会被清除。学习的约定在重启后存活 - 它们持久存储在 `data/conventions.json` 中。
- **目前无身份验证。** 每个会话的凭证绑定处于第四个里程碑；在此之前，可以访问端口的任何人都可以查询，Jira 身份验证来自后端的配置文件。保持默认的环回绑定 (`127.0.0.1`) 除非您位于受信任的网络中。
### 5. 在 AtlasMind 浏览器 UI 中显示结果（show_in_ui）
`query_jira` 接受一个可选的 `show_in_ui: true` 标志。在查询成功后，Netra-mcp 将 `<generated JQL> /raw`（将标志附加在 JQL 之后，因此桥接器将其读取为命令）推送到活动 AtlasMind 聊天窗口中，通过前端 UI 桥接服务器的 `POST /api/mcp/inject` 端点（合同：`docs/frontendui_bridge_contract.md`）。浏览器通过其正常的发送流程运行它并在屏幕上渲染表格和图表 - 图表仅由前端绘制（单一渲染器原理），并且导出始终在那里只需一步即可获取。
要测试：
1. 启动 frontendUI 桥接服务器（`uv run python main.py` 在 frontendUI 存储库中，端口 8001）并在浏览器选项卡中打开聊天 UI。
2. 如果桥接器配置了 `API_KEY`，请在 `.env` 中设置 `NETRA_FRONTEND__API_KEY`。
3. 使用标志调用工具，例如在检查器中：
`query_jira`，`{"query": "open bugs by assignee as a bar chart", "session_id": "ui-1", "show_in_ui": true}`。
4. 预期：图表出现在浏览器中，并且工具响应带有 `ui_injected: true`。
5. 降级检查：关闭浏览器选项卡并重复 - 查询仍然成功，带有 `ui_injected: false` 和错误注释（“无法访问活动 UI 会话”）；在桥接器根本未运行时也是如此。
注意：注入在每次执行时通过浏览器重新执行 JQL（ `/raw` 标志跳过 LLM 生成，因此仅需一次额外的 Jira 搜索）；它是按合同可选的每个调用，并且默认为关闭。
### 6. 与 atlasMind 后端进行端到端测试
1. 启动后端（`uv run python app.py --server --model groq` 在后端存储库中）端口 8000，并配置其 Jira 配置文件。
2. 可选地，将澄清器指向后端缓存的 Jira 元数据，以便问题使用真实的字段名称：
`NETRA_CLARIFICATION__JIRA_FIELDS_PATH=../AtlasMind/data/<profile>/jira_fields.json`
3. 运行上述任意流程；`query_jira` 响应现在包括生成的 JQL、问题、`display_fields` 和 `chart_spec`，这些是从后端传递的（合同：`docs/atlasmind_lite_api_contract.md`）。
## 人类可验证的查询报告
每次派发的 `query_jira` 调用（无论后端是否成功或失败）也会将降级报告写入 `data/reports/<timestamp>_<session>_<id>.md` 并在 `report_path` 中返回其位置。报告包含原始查询、应用的术语解释（因此，如果错误的学习约定被捕获在输出中）、生成的 JQL、问题表、图表规范和任何警告 - 人类需要的一切都可以在输出中验证。澄清问题不会生成报告。
- 禁用 `NETRA_DELIVERY__ENABLED=false`；更改文件夹 `NETRA_DELIVERY__OUTPUT_DIR`。
- 交付是尽力而为的：失败的写入永远不会使查询失败（在 `errors` 中出现注释）。
- markdown 文件通道是第一个 `BaseDeliveryChannel` 实现（`briefings/delivery.py`）； Teams/Slack/email/Confluence 通道作为子类插件，里程碑 3。
## Docker 和云部署
服务器作为自包含的 Docker 镜像提供。Valkey 捆绑在容器内在环回地址运行 - 不需要外部 Redis/Valkey 服务。完整的运行手册（CF、OCI A1、蓝绿、nginx TLS）：`docs/docker_cf_deployment.md`。
### 本地开发使用 docker-compose
```bash
```
# 从仓库根目录（绝不能从docker/目录）
docker-compose up
curl http://localhost:8765/health # {"status":"ok"}
curl http://localhost:8765/mcp # MCP 端点
`./data` 被挂载到容器中，因此报告和学习到的约定在重启后仍然存在。
### 在本地构建镜像（单架构，快速）
需要 Docker Desktop 4.x+ 及 buildx（默认情况下自带）。
```bash
bash scripts/docker-build-local.sh
```
检测您的本地架构（Intel/AMD 为 `amd64`，Apple Silicon 为 `arm64`），使用 `--load` 构建并将其加载到本地守护进程中，并使用最新的 git 标签（例如 `ghcr.io/sunishbharat/atlasmind-netra-mcp:v0.1.0`）标记镜像，如果不存在标签，则回退到 `:dev`。要覆盖它，请在运行之前设置 `VERSION`：
```bash
# Linux / macOS / Git Bash
VERSION=v0.2.0-dev bash scripts/docker-build-local.sh
VERSION=latest bash scripts/docker-build-local.sh
```
```powershell
# Windows PowerShell
$env:VERSION = "v0.2.0-dev"; bash scripts/docker-build-local.sh
$env:VERSION = "latest"; bash scripts/docker-build-local.sh
```
使用以下命令测试它：
```bash
docker run -p 8765:8765 --env-file .env \
ghcr.io/sunishbharat/atlasmind-netra-mcp:latest
curl http://localhost:8765/health
```
### 发布镜像（CI 构建，多架构）
CI 构建在 git 标签上运行 - 合并到 `main` 不会触发构建。
#### 标签命名规则
| 标签格式 | 示例 | 推送到 GHCR 的镜像 |
|---|---|---|
| 完整发布 | `v0.1.0` | `:0.1.0`, `:0.1`, `:latest`, `:sha-<sha>` |
| 预发布 | `v0.1.0-rc.1` | `:0.1.0-rc.1`, `:sha-<sha>` 仅限 - `:latest` 不被触及 |
在验证管道时使用预发布标签；当确认后，切换到完整的发布标签。
要发布发布镜像，请从 `main` 分支推送版本号标签：
```bash
git tag v0.1.0 -m "Initial release"
git push origin v0.1.0
```
GitHub Actions 构建一个涵盖 `linux/amd64` 和 `linux/arm64` 的多架构清单，并将这些标签推送到 GHCR：
- `ghcr.io/sunishbharat/atlasmind-netra-mcp:0.1.0`
- `ghcr.io/sunishbharat/atlasmind-netra-mcp:0.1`
- `ghcr.io/sunishbharat/atlasmind-netra-mcp:latest` ← 自动添加；请勿推送名为 `latest` 的标签
- `ghcr.io/sunishbharat/atlasmind-netra-mcp:sha-<short-sha>`
Docker 会自动为宿主架构选择正确的层 - 不需要单独的 `-arm64` 标签。要拉取最新的发布版本：
```bash
docker pull ghcr.io/sunishbharat/atlasmind-netra-mcp:latest
docker run -p 8765:8765 --env-file .env \
ghcr.io/sunishbharat/atlasmind-netra-mcp:latest
curl http://localhost:8765/health
```
要测试 CI 而不更新 `:latest`，请推送预发布标签。`metadata-action` 检测到 `-rc.` 后缀并自动抑制 `:latest`：
```bash
git tag v0.1.1-rc.1 -m "Release candidate"
git push origin v0.1.1-rc.1
# 推送 :0.1.1-rc.1 和 :sha-<sha> 仅限；:latest 不被更新
```
在 CI 完成之前删除一个不好的标签（在本地和远程删除它，然后在 GitHub Actions UI 中取消已经开始的作业）：
```bash
git tag -d v0.1.0
git push origin :refs/tags/v0.1.0
```
### 构建和推送多平台（amd64 + arm64，手动 CF 部署）
在第一次推送之前需要一次性 buildx 设置：
```bash
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap
```
如果 `docker buildx inspect --bootstrap` 失败并出现"context canceled"（例如，在 Docker Desktop 重启后），请删除并重新创建构建器：
```bash
docker buildx rm multiarch
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap
```
然后构建和推送（替换为您的注册表）：
```bash
export REGISTRY=ghcr.io/sunishbharat
./scripts/cf-deploy.sh # 构建两个平台，推送到 GHCR，然后 cf push
```
对于多平台构建，`--push` 是强制的；`--load` 仅适用于单架构镜像。对于仅 OCI 的用户，可以在 `cf push` 步骤后停止 - 它需要一个活动的 CF 会话，如果没有，则会失败。
### Cloud Foundry 清单
`manifest.yml.template` 是 CF 应用程序描述符。`cf-deploy.sh` 在部署时将 `DOCKER_IMAGE_TAG` 占位符替换为实际的镜像引用，并将其传递给 `cf push` - 您永远不会编辑模板进行例行部署。
如果您需要在推送之前检查或自定义清单 - 例如，扩展实例或更改内存 - 请手动生成：
```bash
export REGISTRY=ghcr.io/sunishbharat
GIT_SHA=$(git rev-parse --short HEAD)
IMAGE="${REGISTRY}/atlasmind-netra-mcp:${GIT_SHA}"
sed "s|DOCKER_IMAGE_TAG|${IMAGE}|g" manifest.yml.template > manifest.yml
# 查看或编辑 manifest.yml，然后：
cf push atlasmind-netra-mcp -f manifest.yml
```
要部署特定的 CI 构建的发布标签而不是本地 SHA：
```bash
sed "s|DOCKER_IMAGE_TAG|ghcr.io/sunishbharat/atlasmind-netra-mcp:0.1.0|g" \
manifest.yml.template > manifest.yml
cf push atlasmind-netra-mcp -f manifest.yml
```
模板中的默认资源设置（编辑 `manifest.yml.template` 以永久更改）：
| 设置 | 默认值 | 备注 |
|---|---|---|
| `memory` | `512M` | 如果服务器进程在持续负载下增长，请增加 |
| `disk_quota` | `512M` | 涵盖 Python 环境 + 日志文件 |
| `instances` | `1` | 仅在 `NETRA_SERVER__SESSION_BACKEND=valkey` 时扩展 - 内存会话不会在实例之间存活 |
| `health-check-http-endpoint` | `/health` | 不要更改 - CF 不会在此返回 200 时路由流量 |
模板中的两个 Jira 元数据 URL 行被注释掉。当静态文件服务器 (`netra-fields-server`) 部署并设置其路由时，请取消注释：
```yaml
NETRA_CLARIFICATION__JIRA_FIELDS_URL: https://<fields-server-route>/jira_fields.json
NETRA_CLARIFICATION__ALLOWED_VALUES_URL: https://<fields-server-route>/jira_allowed_values.json
```
### CF / OCI 中所需的环境变量
| 变量 | 描述 |
|----------|-------------|
| `GROQ_API_KEY` | LLM API 密钥（默认提供商） |
| `NETRA_LITE__BASE_URL` | AtlasMind 后端 URL，例如 `https://atlasmind.de` |
| `NETRA_LITE__API_KEY` | 后端调用的 X-API-Key（推荐） |
| `NETRA_SERVER__API_KEY` | 保护 MCP HTTP 端点的 X-API-Key（推荐） |
| `NETRA_SERVER__PUBLIC_URL` | 此服务器的公共 URL - 在工具响应中启用 `view_url` |
使用 `cf set-env atlasmind-netra-mcp <VAR> <value>` 设置机密，然后使用 `cf restage atlasmind-netra-mcp`。
### 将 Claude Desktop 连接到部署的服务器
```json
{
"mcpServers": {
"atlasmind-netra": {
"transport": "http",
"url": "https://netra.<CF_DOMAIN>/mcp",
"headers": {
"X-API-Key": "<NETRA_SERVER__API_KEY 值>"
}
}
}
}
```
如果未设置 `NETRA_SERVER__API_KEY`，请省略 `headers`。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器