内容
# SysML v2 MCP 服务器
一个遵循[模型上下文协议（MCP）](https://modelcontextprotocol.io)的服务器，暴露 **SysML v2 REST API** 给 AI 助手，如 Claude、GPT 及其他兼容 MCP 的代理。
支持 **STDIO** （Claude Desktop / Claude Code）和 **Streamable HTTP** （OpenAI Agents SDK / PLMgpt Gateway）传输方式。
> **开源，MIT 许可。无商业意图。**
---
## 兼容后端
该服务器实现了 [OMG 系统建模 API 和服务](https://www.omg.org/spec/SystemsModelingAPI/1.0/Beta1/About-SystemsModelingAPI) 规范，并与任何符合 SysML v2 的服务器配合使用：
| 后端 | 厂商 | 备注 |
|---|---|---|
| **Teamwork Cloud (TWC)** | Dassault Systèmes / 3DS | 完整支持，包括 TWC 特定工具 |
| **SysON** | Eclipse / Obeo | 标准 OMG API 工具；设置 `TWC_SYSMLV2_PATH=/api` |
| **SysML v2 Pilot 实现** | OMG 参考 | 标准 OMG API 工具；通常不需要身份验证令牌 |
| 任何符合 OMG 规范的服务器 | — | 标准 OMG API 工具 |
> 下表中的 **[TWC]** 标记的工具特定于 Teamwork Cloud，不适用于 SysON 或试点实现。
---
## 快速入门
```bash
# 1. 克隆并安装
git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install
# 2. 配置
cp .env.example .env
# 编辑 .env — 至少设置 TWC_BASE_URL 和 TWC_TOKEN
# 3. 构建
npm run build
# 4. 运行（STDIO 模式 — 默认）
npm start
# 以 HTTP 模式运行
MCP_TRANSPORT_MODE=http npm start
```
---
## 配置
复制 `.env.example` 到 `.env` 并为您的后端设置值。所有选项都在 `.env.example` 中有文档记录。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `TWC_BASE_URL` | *(必填)* | 您的 SysML v2 服务器基准 URL |
| `TWC_SYSMLV2_PATH` | `/sysmlv2-api` | API 路径前缀（空字符串 "" 表示 SysON/试点，`/sysmlv2-api` 表示 TWC） |
| `TWC_TOKEN` | *(TWC 必填)* | API 身份验证令牌 |
| `MAGICLAB_BASE_URL` | *(仅 TWC)* | 用于深链接生成的 MagicLab 网页 URL |
| `TWC_INSECURE` | `false` | 跳过 TLS 验证（自签名证书） |
| `MCP_TRANSPORT_MODE` | `stdio` | 传输方式：`stdio` 或 `http` |
| `MCP_HTTP_PORT` | `3001` | HTTP 端口（当 mode=http 时） |
### 后端特定设置
**Teamwork Cloud (TWC)**
```env
TWC_BASE_URL=https://your-twc-server:8443
TWC_SYSMLV2_PATH=/sysmlv2-api
TWC_TOKEN=your-api-token
MAGICLAB_BASE_URL=https://your-twc-server:8443/magiclab
TWC_INSECURE=true # 如果使用自签名证书
```
**SysON**
```env
TWC_BASE_URL=http://localhost:8080
TWC_SYSMLV2_PATH=
TWC_TOKEN= # 如果 SysON 没有身份验证，则留空
TWC_INSECURE=false
```
**SysML v2 Pilot 实现（参考服务器）**
```env
TWC_BASE_URL=http://localhost:9000
TWC_SYSMLV2_PATH=
TWC_TOKEN= # 参考服务器上没有身份验证
TWC_INSECURE=false
```
---
## Claude Desktop 设置（逐步指南）
该服务器已在 **Claude Desktop** 上测试和验证。
### 步骤 1 — 克隆并安装
```bash
git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install
```
### 步骤 2 — 配置您的环境
```bash
cp .env.example .env
```
打开 `.env` 并至少设置：
```env
TWC_BASE_URL=https://your-sysmlv2-server:8443
TWC_TOKEN=your-api-token
```
参见 [配置](#配置) 部分获取所有选项和后端特定示例。
### 步骤 3 — 构建
```bash
npm run build
```
这会将 TypeScript 编译为 `dist/index.js`。
### 步骤 4 — 配置 Claude Desktop
打开（或创建）您的 Claude Desktop 配置文件：
| 平台 | 路径 |
|---|---|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
添加以下内容（调整路径到您克隆存储库的位置）：
**macOS / Linux**
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["/absolute/path/to/sysmlv2-mcp-server/dist/index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-api-token",
"TWC_SYSMLV2_PATH": "/sysmlv2-api",
"TWC_INSECURE": "true"
}
}
}
}
```
**Windows**
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["C:\\path\\to\\sysmlv2-mcp-server\\dist\\index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-api-token",
"TWC_SYSMLV2_PATH": "/sysmlv2-api",
"TWC_INSECURE": "true"
}
}
}
}
```
> **提示：** 您可以直接在配置 `env` 块中传递所有环境变量，而不是使用 `.env` 文件 — Claude Desktop 将在启动服务器时注入它们。
### 步骤 5 — 重启 Claude Desktop
完全退出并重新启动 Claude Desktop。您应该在工具面板（锤子图标）中看到 SysML v2 工具。
### 步骤 6 — 验证
尝试询问 Claude：
> *"列出所有我的 SysML v2 项目"*
如果服务器已连接，Claude 将调用 `sysmlv2_get_projects` 并返回您的项目列表。
有关更多示例提示，请参见 [EXAMPLES.md](./EXAMPLES.md)。
---
## 传输模式
### STDIO（默认）
适用于 Claude Desktop、Claude Code 或任何将服务器作为子进程启动的 MCP 客户端。
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["/path/to/sysmlv2-mcp-server/dist/index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-token"
}
}
}
}
```
### Streamable HTTP
适用于 OpenAI Agents SDK、PLMgpt Gateway 或基于 Web 的 MCP 客户端。
```bash
MCP_TRANSPORT_MODE=http MCP_HTTP_PORT=3001 npm start
```
端点：
- `POST /mcp` — Streamable HTTP（主要）
- `GET /sse` — SSE（旧版）
- `GET /health` — 健康检查
---
## 工具（共 38 个）
### 项目服务（5）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_projects` | 列出所有项目 |
| `sysmlv2_get_project` | 按 ID 获取项目 |
| `sysmlv2_create_project` | 创建新项目 |
| `sysmlv2_update_project` | 更新项目名称 / 描述 |
| `sysmlv2_delete_project` | 删除项目（不可逆） |
### 提交服务（6）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_commits` | 列出项目的提交记录 |
| `sysmlv2_get_commit` | 按 ID 获取提交记录 |
| `sysmlv2_create_commit` | 创建新的提交记录，可选变更集 |
| `sysmlv2_diff_commits` | 比较两个提交记录（ADDED / UPDATED / DELETED） |
| `sysmlv2_get_commit_changes` | 获取提交记录的变更集 |
| `sysmlv2_get_commit_change` | 获取特定的变更记录 |
### 分支服务（5）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_branches` | 列出分支 |
| `sysmlv2_get_branch` | 按 ID 获取分支 |
| `sysmlv2_create_branch` | 创建新分支 |
| `sysmlv2_delete_branch` | 删除分支（不可逆） |
| `sysmlv2_merge_branch` | 将源提交记录合并到目标分支 |
### 标签服务（4）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_tags` | 列出标签 |
| `sysmlv2_get_tag` | 按 ID 获取标签 |
| `sysmlv2_create_tag` | 在提交记录上创建标签 |
| `sysmlv2_delete_tag` | 删除标签 |
### 元素导航（4）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_elements` | 获取所有元素（分页） |
| `sysmlv2_get_element` | 按 ID 获取元素 |
| `sysmlv2_get_roots` | 获取根元素 — 模型遍历的入口点 |
| `sysmlv2_get_element_relationships` | 获取元素关系（IN / OUT / BOTH） |
### 查询服务（7）— 标准 OMG API
| 工具 | 描述 |
|---|---|
| `sysmlv2_get_queries` | 列出已保存的查询 |
| `sysmlv2_get_query` | 按 ID 获取查询 |
| `sysmlv2_create_query` | 创建已保存的查询 |
| `sysmlv2_update_query` | 更新已保存的查询 |
| `sysmlv2_delete_query` | 删除已保存的查询 |
| `sysmlv2_execute_query` | 执行即席查询 |
| `sysmlv2_execute_query_by_id` | 按 ID 执行已保存的查询 |
### 评估服务（3）— **[TWC 专用]**
> 这些工具使用 Teamwork Cloud 的参数化评估扩展，不是标准 OMG API 的一部分。它们在 SysON 或试点实现上不起作用。
| 工具 | 描述 |
|---|---|
| `sysmlv2_evaluate` | 在项目级别评估参数化模型 |
| `sysmlv2_evaluate_commit` | 在特定的提交记录中评估参数化模型 |
| `sysmlv2_export_evaluation_table` | 以表格形式导出评估结果（项目级别） |
| `sysmlv2_evaluate_commit_table` | 以表格形式导出特定提交记录的评估结果 |
### 便捷工具（3）
| 工具 | 后端 | 描述 |
|---|---|---|
| `sysmlv2_get_requirements` | 所有 | 通过服务器端过滤查询所有 RequirementUsage 元素 |
| `sysmlv2_get_views` | **[TWC]** | 查询 ViewUsage 元素 + MagicLab 深链接 |
| `sysmlv2_open_magiclab` | **[TWC]** | 为项目或元素生成 MagicLab URL |
---
## 身份验证
服务器按以下顺序尝试身份验证，并在第一个成功时停止：
1. `Token {TWC_TOKEN}` 头 — TWC 默认
2. `Bearer {TWC_TOKEN}` 头 — OAuth / 标准 JWT
3. 无身份验证 — 对于开放/未经身份验证的服务器（例如本地试点）
---
## 架构
```
src/index.ts 单文件 MCP 服务器
├── Config 基于环境的配置
├── HTTP 助手 apiRequest() 带有多身份验证回退
├── 分页 Link-header 基于分页的 paginatedGet()
├── SysMLv2MCPServer 主要类
│ ├── registerProjectTools()
│ ├── registerCommitTools()
│ ├── registerBranchTools()
│ ├── registerTagTools()
│ ├── registerElementTools()
│ ├── registerQueryTools()
│ ├── registerEvaluationTools() ← TWC 特定
│ ├── registerConvenienceTools()
│ ├── runStdio()
│ └── runHTTP()
└── 自动运行 直接执行时 STDIO
```
要添加新工具，请在类中创建 `registerXxxTools()` 方法，并从 `registerAllTools()` 调用它。
---
## HTTP 模式下的导入
```typescript
import { mcpServer, SysMLv2MCPServer } from "./dist/index.js";
// 以 HTTP 模式运行
mcpServer.run("http");
```
---
## 贡献
欢迎贡献。要添加新工具或后端特定扩展：
1. 在 `SysMLv2MCPServer` 中添加 `registerXxxTools()` 方法
2. 从 `registerAllTools()` 调用它
3. 如果工具是后端特定的，请在 README 工具表中添加 `[TWC]` / `[SysON]` 标记
4. 提交带有简要描述您正在包装的 API 端点的 PR
---
## 许可证
MIT — 免费使用、修改和分发，需注明出处。
---
## 发布到 GitHub
### 前提条件
- 一个 [GitHub 账户](https://github.com)
- [Git](https://git-scm.com/downloads) 安装在您的机器上
- [GitHub CLI](https://cli.github.com) （可选但更方便）
---
### 选项 A — 使用 GitHub CLI（推荐，最简单）
**步骤 1 — 安装 GitHub CLI** （如果尚未安装）
```bash
# macOS
brew install gh
# Windows（通过 winget）
winget install GitHub.cli
```
**步骤 2 — 登录**
```bash
gh auth login
```
按照提示 — 选择 GitHub.com → HTTPS → 通过浏览器身份验证。
**步骤 3 — 导航到发布文件夹**
```bash
# macOS / Linux
cd /path/to/mcp-sysmlv2-server-release
# Windows
cd C:\path\to\mcp-sysmlv2-server-release
```
**步骤 4 — 初始化 git 并一次性创建存储库**
```bash
git init
git add .
git commit -m "初始发布"
gh repo create sysmlv2-mcp-server \
--public \
--description "MCP 服务器，暴露 SysML v2 REST API 给 AI 助手（Claude、OpenAI Agents）。MIT 许可。" \
--push \
--source .
```
完成 — 您的存储库已在 `https://github.com/<您的用户名>/sysmlv2-mcp-server` 上线。
---
### 选项 B — 使用 Git + GitHub 网站（手动）
**步骤 1 — 在 GitHub 上创建新存储库**
1. 前往 [https://github.com/new](https://github.com/new)
2. 设置存储库名称：`sysmlv2-mcp-server`
3. 设置描述：`MCP 服务器，暴露 SysML v2 REST API 给 AI 助手。MIT 许可。`
4. 设置可见性：**公共**
5. **不要** 勾选 “添加 README”、 “.gitignore” 或 “选择许可证” — 存储库必须为空
6. 点击 **创建存储库**
7. 复制显示的存储库 URL（例如 `https://github.com/<您的用户名>/sysmlv2-mcp-server.git`）
**步骤 2 — 在发布文件夹中初始化 git**
```bash
cd /path/to/mcp-sysmlv2-server-release
git init
```
**步骤 3 — 暂存所有文件**
```bash
git add .
```
**步骤 4 — 验证没有敏感信息**
```bash
git status
```
您应该只看到：`src/index.ts`、`package.json`、`tsconfig.json`、`.env.example`、`README.md`、`EXAMPLES.md`、`.gitignore`。
没有 `.env`、没有 `node_modules/`、没有 `dist/`。
**步骤 5 — 创建第一个提交**
```bash
git commit -m "初始发布 — SysML v2 MCP 服务器 v1.0.0"
```
**步骤 6 — 添加远程并推送**
```bash
git remote add origin https://github.com/<您的用户名>/sysmlv2-mcp-server.git
git branch -M main
git push -u origin main
```
**步骤 7 — 在 GitHub 上添加许可证**
1. 前往您的新存储库，网址为 GitHub
2. 点击 **添加文件 → 创建新文件**
3. 命名为 `LICENSE`
4. 点击 **选择许可证模板** → 选择 **MIT**
5. 填写您的姓名 → **审查并提交**
---
### 发布后 — 推荐的 GitHub 设置
**添加主题** （提高可发现性）：
前往您的存储库，点击 “About” 旁边的 ⚙️ 齿轮图标 → 添加主题：
`sysml` `sysmlv2` `mcp` `mbse` `model-context-protocol` `teamwork-cloud` `claude` `ai` `systems-engineering`
**更新 README 存储库 URL：**
在 `README.md` 中，将：
```
git clone https://github.com/your-org/sysmlv2-mcp-server.git
```
替换为您的实际 URL：
```
git clone https://github.com/<您的用户名>/sysmlv2-mcp-server.git
```
然后提交并推送：
```bash
git add README.md
git commit -m "修复克隆 URL 到实际存储库"
git push
```
**添加发布标签：**
```bash
git tag -a v1.0.0 -m "v1.0.0 — 初始公开发布"
git push origin v1.0.0
```
然后在 GitHub 上前往 **Releases → 草拟新发布** → 选择 `v1.0.0` → 编写发布说明 → 发布。
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器