fusion-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion MCP Setup Guide

Fusion MCP 设置指南

When to use

适用场景

Use this skill when a user asks:

what Fusion MCP is
what it can do
how to install/configure it
how to verify that it is working
how to troubleshoot a failing Fusion MCP setup

Typical triggers:

"what is fusion mcp"
"help me set up fusion mcp"
"how do I use fusion mcp with copilot"

当用户提出以下问题时使用本技能：

什么是Fusion MCP
它能实现什么功能
如何安装/配置它
如何验证它是否正常运行
如何排查Fusion MCP设置失败的问题

典型触发提问：

“什么是Fusion MCP”
“帮我设置Fusion MCP”
“如何在Copilot中使用Fusion MCP”

When not to use

不适用场景

Do not use this skill for:

implementing product features unrelated to MCP setup
making destructive environment changes without user confirmation
assuming private repository details that are not visible

请勿在以下场景使用本技能：

实现与MCP设置无关的产品功能
在未获得用户确认的情况下执行会破坏环境的变更
假设不可见的私有仓库细节

Required inputs

必要输入信息

Collect before proposing setup steps:

user environment (OS, shell, editor/runtime)
target client where MCP will run (for example VS Code MCP config or terminal)
whether the user wants released image (GHCR) or local build from source
transport mode (
```
stdio
```
for editor client config or HTTP endpoint for local checks)
whether required access is ready (Docker, GitHub auth for GHCR, API keys)

If details are missing, ask concise follow-up questions first.

在提供设置步骤前需收集：

用户环境（操作系统、Shell、编辑器/运行时）
MCP将运行的目标客户端（例如VS Code MCP配置或终端）
用户希望使用已发布镜像（GHCR）还是从源码本地构建
传输模式（编辑器客户端配置使用
```
stdio
```
，本地检查使用HTTP端点）
是否已准备好所需访问权限（Docker、GHCR的GitHub认证、API密钥）

若信息缺失，先提出简洁的跟进问题。

Instructions

操作步骤

Explain what this MCP server provides:
- Fusion-oriented MCP capabilities for retrieval and workflow support
- tool surface may evolve over time as the server is a PoC
- examples today may include retrieval, index guidance, metadata summaries, and skill discovery
Use the official README quick start as source of truth, then present a minimal 2-step setup path:
- choose image source: GHCR release image or local build
- configure VS Code MCP using Docker
```
stdio
```
  only (scope for this iteration)

For GHCR image setup, include auth prerequisites before pull/run:

```
gh auth login -h github.com -w
```

gh auth refresh -h github.com -s read:packages

gh auth token | docker login ghcr.io -u <github-username> --password-stdin

For local build setup, use the documented sequence so the API is built, started, and validated:
- ```
cp .env.example .env
```
- ```
docker compose up -d --build api
```
- then follow the health-check step in
```
references/local-http-quickstart.md
```
  to confirm the API is healthy
Provide required configuration categories without exposing secret values:
- Azure Search keys (
```
AzureSearch__*
```
  )
- Foundry keys/settings (
```
Foundry__*
```
  )
- optional runtime vars (
```
ASPNETCORE_ENVIRONMENT
```
  ,
```
HOST_PORT
```
  )
Provide a lightweight MCP smell test:
- run
```
initialize
```
  and confirm a successful response
- run
```
tools/list
```
  and confirm at least one tool is returned
- run one non-destructive
```
tools/call
```
  against an available tool
- pass criteria: call response is non-empty (
```
content
```
  or
```
structuredContent
```
  contains data)
- note: do not hard-code a fixed tool list; tool inventory can change between versions
Troubleshoot in documented order:
- GHCR
```
unauthorized
```
  /
```
403
```
  -> refresh GH auth and Docker login
- Apple Silicon manifest mismatch -> add Docker arg
```
--platform linux/amd64
```
- ```
tools/list
```
  returns empty or basic query fails -> re-check API key env mapping and MCP server selection in VS Code
- startup looks healthy but tool behavior is partial -> re-check env/config/auth alignment and restart MCP server
When MCP setup fails, MCP behavior is incorrect, or the user asks to file a bug, produce a bug report draft from
```
assets/bug-report-template.md
```
.
- default target repository:
```
equinor/fusion-poc-mcp
```
- include concrete repro steps, expected vs actual behavior, and troubleshooting already attempted
- include non-sensitive environment details (OS, VS Code version, Docker version, image tag, transport mode)
- never include secrets, API keys, or raw token values
For uncertainty or repo-private constraints, state assumptions explicitly and link to authoritative docs instead of guessing.

解释本MCP服务器的功能：
- 为检索和工作流支持提供面向Fusion的MCP能力
- 由于该服务器是PoC（概念验证），工具功能范围可能会随时间演进
- 当前示例功能可能包括检索、索引指导、元数据摘要和技能发现
以官方README快速入门指南为权威依据，提供极简的两步设置流程：
- 选择镜像来源：GHCR发布镜像或本地构建
- 仅使用Docker
```
stdio
```
  配置VS Code MCP（本迭代的适用范围）

对于GHCR镜像设置，在拉取/运行前包含认证前提条件：

```
gh auth login -h github.com -w
```

gh auth refresh -h github.com -s read:packages

gh auth token | docker login ghcr.io -u <github-username> --password-stdin

对于本地构建设置，按照文档步骤执行，确保API完成构建、启动和验证：
- ```
cp .env.example .env
```
- ```
docker compose up -d --build api
```
- 随后按照
```
references/local-http-quickstart.md
```
  中的健康检查步骤确认API状态正常
提供必要的配置类别，但不得暴露敏感值：
- Azure Search密钥（
```
AzureSearch__*
```
  ）
- Foundry密钥/设置（
```
Foundry__*
```
  ）
- 可选运行时变量（
```
ASPNETCORE_ENVIRONMENT
```
  、
```
HOST_PORT
```
  ）
提供轻量级MCP验证测试：
- 运行
```
initialize
```
  并确认响应成功
- 运行
```
tools/list
```
  并确认至少返回一个工具
- 针对可用工具执行一次非破坏性的
```
tools/call
```
- 通过标准：调用响应非空（
```
content
```
  或
```
structuredContent
```
  包含数据）
- 注意：不要硬编码固定工具列表；工具清单可能会随版本变化
按照文档顺序排查问题：
- GHCR出现
```
unauthorized
```
  /
```
403
```
  错误 -> 刷新GH认证并重新登录Docker
- Apple Silicon镜像清单不匹配 -> 添加Docker参数
```
--platform linux/amd64
```
- ```
tools/list
```
  返回空或基础查询失败 -> 重新检查API密钥环境变量映射以及VS Code中的MCP服务器选择
- 启动状态正常但工具行为异常 -> 重新检查环境/配置/认证的一致性，然后重启MCP服务器
当MCP设置失败、行为异常或用户要求提交Bug时，根据
```
assets/bug-report-template.md
```
生成Bug报告草稿：
- 默认目标仓库：
```
equinor/fusion-poc-mcp
```
- 包含具体的重现步骤、预期与实际行为，以及已尝试的排查操作
- 包含非敏感的环境细节（操作系统、VS Code版本、Docker版本、镜像标签、传输模式）
- 绝对不要包含密钥、API密钥或原始令牌值
若存在不确定性或仓库私有限制，需明确说明假设，并链接到权威文档，而非猜测。

Expected output

预期输出

Return:

short explanation of Fusion MCP and when to use it
setup path tailored to the user environment (GHCR/local,
```
stdio
```
/HTTP)
minimal validation checklist with concrete pass criteria
troubleshooting steps mapped to observed error symptoms
bug report draft (when setup fails/misbehaves or user requests) using
```
assets/bug-report-template.md
```
with default target
```
equinor/fusion-poc-mcp
```
script snippets when user asks for copy/paste automation aids
assumptions and missing information called out explicitly
links to the exact upstream docs used

返回内容包括：

Fusion MCP的简短说明及其适用场景
适配用户环境的设置流程（GHCR/本地构建、
```
stdio
```
/HTTP）
带有具体通过标准的极简验证清单
与观察到的错误症状对应的排查步骤
（当设置失败/行为异常或用户请求时）使用
```
assets/bug-report-template.md
```
生成的Bug报告草稿，默认目标仓库为
```
equinor/fusion-poc-mcp
```
当用户需要复制粘贴的自动化辅助时提供脚本片段
明确指出假设和缺失信息
链接到所使用的上游权威文档

References

参考资料

references/README.md
assets/bug-report-template.md

references/README.md
assets/bug-report-template.md

Safety & constraints

安全与约束

Never:

request or expose secrets, tokens, or credentials
invent setup commands that are not supported by project documentation
claim setup succeeded without validation output
run destructive commands without explicit user confirmation

Always:

prefer official repository documentation as source of truth
provide least-privilege, minimal-change setup guidance first
separate confirmed facts from assumptions
keep guidance scoped to VS Code + Docker for this iteration

绝对禁止：

请求或暴露密钥、令牌或凭证
发明项目文档不支持的设置命令
在无验证输出的情况下宣称设置成功
在未获得用户明确确认的情况下执行破坏性命令

必须遵守：

优先以官方仓库文档为权威依据
首先提供最小权限、最小变更的设置指导
区分已确认事实与假设
本迭代的指导范围仅限VS Code + Docker