Windchill MCP 服务器
针对PTC Windchill 13.0.2.x版本，我们开发了一个全面的模型上下文协议（MCP）服务器，该服务器使Claude及其他AI助手能够通过一个标准化接口与Windchill PLM系统进行交互，该接口支持7个专门代理中的64多种工具，包括动态服务器切换功能。
🚀 快速入门
与Claude Desktop一起使用
最快开始使用的方法是利用这台服务器 Claude 桌面版：
# Clone and build
git clone
cd windchill-mcp-server
npm install
npm run build
# Configure Claude Desktop (see docs/CLAUDE_DESKTOP.md for details)
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# or: %APPDATA%\Claude\claude_desktop_config.json (Windows)📖 完整的Claude桌面设置指南： 文件/CLAUDE_DESKTOP.md
______________________________________________________________________
本地开发与网页用户界面
选项1：安装向导（最简单）
chmod +x docker/setup-wizard.sh
./docker/setup-wizard.sh向导将：
- 进行飞行前检查
- 配置您的环境
- 启动服务器
- 运行自动化测试
选项2：手动设置
本地开发
# Install dependencies
npm install
cd angular-ui && npm install && cd ..
# Configure environment
cp docker/.env.example docker/.env
# Edit .env with your Windchill credentials
# Run in development mode (starts both MCP server + Angular UI)
npm run dev
# Or run services separately:
npm run dev:server # MCP server only (port 3000)
npm run dev:ui # Angular UI only (port 4200)这个（或“该”） npm run dev 命令开始：
- MCP 服务器 在 http://localhost:3000 上（支持热重载）
- Angular 用户界面 在 http://localhost:4200 上（通过代理连接到端口 3000）
Docker 部署
生产
# Make scripts executable
chmod +x docker/docker-run.sh
# Build and run
./docker/docker-run.sh
# Or using npm scripts
npm run docker:build
npm run docker:up访问应用程序
启动容器后，可通过以下地址访问应用程序：
- Angular 网页用户界面：
http://localhost:4200- 所有MCP工具的现代网页界面，支持JSON-RPC 2.0 - MCP服务器API：
http://localhost:3000/api/- 直接访问所有工具的API（符合JSON-RPC 2.0标准） - MCP 服务器信息：
http://localhost:3000- 服务器健康状况和信息
热重载开发
# Make scripts executable
chmod +x docker/docker-dev.sh
# Run development container
./docker/docker-dev.sh
# Or using npm scripts
npm run docker:dev仅部署Angular用户界面
# Make deployment script executable
chmod +x docker/deploy-ui.sh
# Deploy Angular UI (requires MCP server to be running)
./docker/deploy-ui.sh
# Or using npm scripts
npm run deploy:ui部署完整系统
# Deploy both MCP server and Angular UI
npm run deploy:all
# Or manually
docker compose -f docker/docker-compose.yml up -d验证Docker环境
# Verify Docker setup before deployment
./docker/verify-docker.sh
# Or using npm
npm run verify:docker有关详细的Docker设置，请参阅
🌐 网页界面
Angular MCP 工具用户界面
该服务器包含一个基于现代Angular的网页界面，提供：
- MCP JSON-RPC 2.0 合规性全面支持标准化的MCP协议
- 交互式工具发现浏览并搜索可用工具，同时应用筛选条件
- 动态表单生成基于JSON Schema的自动参数输入表单
- 实时工具执行直接从网页界面执行工具
- 响应可视化工具执行结果的格式化显示
- 错误处理全面的错误报告和调试信息
使用网页界面
- 访问导航至
http://localhost:4200启动容器后
- *注：4200端口是Angular CLI的标准开发端口*
- 发现工具按代理或类别浏览可用工具
- 筛选与搜索使用搜索栏和筛选器来查找特定工具
- 执行工具点击任意工具以打开执行界面
- 查看结果查看格式化响应并优雅地处理错误
MCP协议支持
网页界面完全实现了MCP JSON-RPC 2.0规范：
// Example MCP JSON-RPC 2.0 request
{
"jsonrpc": "2.0",
"id": "req_123",
"method": "tools/list",
"params": {}
}
// Example tool execution request
{
"jsonrpc": "2.0",
"id": "req_456",
"method": "tools/call",
"params": {
"name": "document_create",
"arguments": {
"number": "DOC-123",
"name": "New Document",
"type": "SPEC"
}
}
}📋 功能特性
最新增强功能（v1.2.0）
Claude桌面集成：
- ✅ 原生stdio支持 为了实现与Claude Desktop的无缝集成
- ✅ 仅标准输入输出模式 (
MCP_STDIO_ONLY=true) - 禁用HTTP服务器以实现更简洁的操作 - ✅ 优化日志记录 - 在stdio模式下仅记录文件
- ✅ 包裹条码录入 - 可作为命令行工具安装
- ✅ 翻译为中文是：✅（这个符号本身没有具体的中文含义，通常用于表示正确、确认或完成等意思，在中文语境中可以保持原样或根据上下文解释为“正确”、“确认”等）。如果仅就符号本身而言，中文中没有直接对应的翻译，但可以根据其用途来解释其意义。 全面设置指南 - docs/CLAUDE_DESKTOP.md 翻译为中文是：docs/CLAUDE_桌面版.md
之前的增强功能（v1.1.0）
文档代理扩展文档代理已显著增强，新增了22项工具：
- Angular 用户界面部署使用多阶段构建完成Docker部署配置
- MCP JSON-RPC 2.0 支持服务器和客户端均完全遵循协议规范
- Docker 构建修复将 Angular UI 的构建过程从使用 \
npm ci\更改为使用 \npm install\（在构建过程中生成 package-lock.json 文件） - Angular 配置修复移除了导致构建失败的环境文件依赖和Angular Material引用
- HTML模板修复修复了Angular组件模板中未闭合的textarea标签
- Polyfill 配置为polyfills添加了适当的TypeScript编译配置
- Polyfill导入修复简化了 polyfills.ts 文件，移除了 @angular/localize/init 并修复了 zone.js 的导入路径
- Nginx 配置修复从gzip_proxied配置中移除了无效的“must-revalidate”指令
- 用户界面性能修复添加了防抖搜索输入和安全的JSON显示功能，以防止浏览器冻结
- TypeScript 修复修复了 NodeJS.Timeout 类型的使用问题以及 HttpClient 响应类型处理
- 依赖项更新将Angular从v17更新到v18，并抑制了npm的弃用警告
- 22种新工具 在优先级1-3的实施层级中增加
- 增强型API服务 支持使用PATCH方法和多部分表单数据
- 全面的错误处理 带有适当的TypeScript类型定义
- 高级搜索功能 带有日期范围和生命周期状态过滤功能
- 批量操作 为了高效地进行批处理
- 内容管理 支持上传/下载及附件处理
- 关系管理 用于文档链接和引用
代理
- 部分代理部件管理、物料清单（BOM）结构、部件搜索（24种工具）
- 文档代理全面的文档管理，配备25种工具：
- 核心生命周期创建、更新、检出、检入、修订文档 - 版本管理版本历史、迭代、迭代说明 - 内容管理上传/下载内容，处理附件 - 关系管理文档引用和链接 - 高级搜索使用日期/生命周期过滤器进行多标准搜索 - 批量操作批量更新和生命周期操作
- 变革推动者变更请求管理（16种工具）
- 工作流代理工作流项目和流程（~12种工具）
- 项目代理项目管理操作（约10种工具）
- DataAdmin 代理容器/上下文发现与管理（13种工具）
- 容器发现列出产品、库、组织、项目 - 结构导航文件夹及文件夹内容 - 配置管理产品/库的选项池和选项集
- ServerManager 代理多服务器管理与切换（5种工具） 新
- 服务器发现列出所有已配置服务器及其连接详情 - 动态切换在运行时切换生产/开发/测试环境 - 连接测试在切换前测试服务器连接性 - 会话管理获取当前服务器及详细服务器信息
能力
- 基于会话的认证与CSRF令牌管理
- 会话过期时自动重新认证
- 全面支持HTTP方法（GET、POST、PUT、PATCH、DELETE）
- 对所有端点支持OData查询，具备高级过滤功能
- 支持文件上传的多部分表单数据
- 可扩展的基于代理的架构
- 全面的错误处理和日志记录
- 批量操作支持，以实现高效处理
🏗️ 建筑
windchill-mcp-server/
├── src/
│ ├── agents/ # Agent implementations
│ │ ├── base-agent.ts
│ │ ├── part-agent.ts
│ │ ├── change-agent.ts
│ │ ├── document-agent.ts
│ │ ├── workflow-agent.ts
│ │ └── project-agent.ts
│ ├── config/ # Configuration
│ │ └── windchill.ts
│ ├── services/ # API services
│ │ └── windchill-api.ts
│ └── index.ts # Main entry point
├── docker/
│ ├── Dockerfile # Production container
│ ├── Dockerfile.dev # Development container
│ ├── docker-compose.yml # Production compose
│ ├── docker-compose.dev.yml # Development compose
│ ├── .env.example # Environment template
│ └── *.sh # Setup and run scripts
└── docs/ # Documentation files🔧 配置
环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
WINDCHILL_URL | 是 | - | 风寒基准URL |
WINDCHILL_USER | 是 | - | 风寒用户名 |
WINDCHILL_PASSWORD | 是 | - | 风寒密码 |
MCP_STDIO_ONLY | No | false | 仅标准输入输出模式（推荐用于Claude Desktop） |
MCP_SERVER_NAME | 编号 | windchill-mcp | MCP 服务器名称 |
MCP_SERVER_VERSION | 序号 | 1.0.0 | 服务器版本 |
MCP_SERVER_PORT | 编号 | 3000 | 服务器端口（当 MCP_STDIO_ONLY=true 时忽略） |
LOG_LEVEL | 编号 | 信息 | 日志级别（Claude Desktop 使用 'error'） |
📚 API 接口端点
服务器使用带有OData端点的Windchill REST API：
/ProdMgmt/Parts- 零件管理/DocMgmt/Documents- 文档管理/ChangeMgmt/ChangeRequests- 变更管理/WorkflowMgmt/WorkItems- 工作流管理/ProjMgmt/Projects- 项目管理
🛠️ 开发
可用脚本
# Local development
npm run dev # Start with hot reload
npm run build # Build TypeScript
npm start # Run production build
# Docker
npm run docker:build # Build Docker image
npm run docker:up # Start container
npm run docker:down # Stop container
npm run docker:logs # View logs
npm run docker:dev # Start development container添加新代理
- 在（指定位置）创建代理文件
src/agents/：
import { BaseAgent } from "./base-agent.js";
export class MyAgent extends BaseAgent {
protected agentName = "my-agent";
protected tools = [
{
name: "my_tool",
description: "Tool description",
inputSchema: {
/* JSON schema */
},
handler: async (params) => {
/* implementation */
},
},
];
}- 注册于
src/index.ts：
import { MyAgent } from "./agents/my-agent.js";
const agents = {
// ... existing agents
myAgent: new MyAgent(),
};🐳 Docker 详细信息
生产容器
- 基地Node.js 20 Alpine（阿尔卑斯）版
- 用户非根用户（nodejs:1001）
- 港口3000
- 健康检查30秒间隔
Angular 用户界面容器
- 基地多阶段构建（Node.js 20 + Nginx Alpine）
- 构建阶段使用 \
npm install\将 Angular 的 TypeScript 编译为 JavaScript - 生产阶段Nginx通过API代理提供静态文件服务
- 港口8080（内部），映射到4200（外部）
- API代理路线
/api/*向MCP服务器发送的请求 - SPA 支持处理Angular的客户端路由
- 依赖管理在构建过程中生成 package-lock.json 文件
开发容器
- 热重载通过 ts-node-dev 启用
- 源安装实时代码更新
- 调试日志记录已启用
看 以获取完整的Docker文档。
🔐 安全
- 基于会话的认证，使用CSRF令牌
- 非root容器用户
- 基于环境的密钥
- 已启用健康检查
- 通过Docker网络实现网络隔离
📊 与数据平台的集成
这个MCP服务器是更大数据平台架构的一部分：
Data Sources (PLM/ERP/MES) → MCP Agents → Kafka → Data Lake → Analytics见 IT Architecture.mmd 以下是完整的架构图。
🐛 故障排除
认证失败
- 验证WINDCHILL_URL是否可访问
- 检查 .env 文件中的用户名/密码
- 确保Windchill REST API已启用
集装箱问题
# View logs
docker-compose logs -f
# Check container status
docker-compose ps
# Restart container
docker-compose restart连接问题
# Test Windchill connectivity from container
docker exec windchill-mcp-server ping plm.windchill.com🖥️ Claude 桌面版 vs 网页版界面
此服务器支持两种不同的使用模式：
克劳德桌面模式（推荐）
使用 MCP_STDIO_ONLY=true 对于：
- ✅ 与Claude桌面应用程序集成
- ✅ 基于Stdio的MCP协议通信
- ✅ 仅文件日志记录（无控制台输出）
- ✅ 无HTTP服务器开销
- ✅ 简化配置
看见： docs/CLAUDE_DESKTOP.md 翻译为中文是：docs/CLAUDE桌面版.md
Web 用户界面模式
默认模式，带有HTTP服务器，用于：
- ✅ 在端口4200上运行的交互式Angular网页界面
- ✅ 3000端口上的REST API
- ✅ 多服务器切换能力
- ✅ 实时工具测试
- ✅ 支持Docker部署
见上面的Docker部署部分
📝 许可证
ISC（International Security Cooperation，国际安全合作）
🤝 贡献（或“参与贡献”）
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支
- 提交您的更改
- 推送到分支
- 打开一个拉取请求
📞 支持
对于问题和疑问：
- 检查 针对Docker特有的问题
- 检查 CLAUDE.md（文件名，可翻译为“克劳德文档”或保持原样，具体取决于上下文和用途） 用于开发指南
- 审查日志：
docker-compose logs -f