Cars-10/windchill-mcp-server

Windchill MCP Server

A comprehensive Model Context Protocol (MCP) server for PTC Windchill 13.0.2.x that enables Claude and other AI assistants to interact with Windchill PLM systems through a standardized interface with 64+ tools across 7 specialized agents, including dynamic server switching.

🚀 Quick Start

Using with Claude Desktop

The fastest way to get started is to use this server with Claude Desktop:

# Clone and build
git clone <your-repo-url>
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)

📖 Full Claude Desktop setup guide:

Local Development & Web UI

Option 1: Setup Wizard (Easiest)

chmod +x docker/setup-wizard.sh
./docker/setup-wizard.sh

The wizard will:

1. Run pre-flight checks
2. Configure your environment
3. Start the server
4. Run automated tests

Option 2: Manual Setup

Local Development

# 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)

The npm run dev command starts:

• MCP Server on http://localhost:3000 (with hot reload)
• Angular UI on http://localhost:4200 (with proxy to port 3000)

Docker Deployment

Production

# 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

Accessing the Applications

After starting the containers, access the applications at:

• Angular Web UI: http://localhost:4200 - Modern web interface for all MCP tools with JSON-RPC 2.0 support
• MCP Server API: http://localhost:3000/api/ - Direct API access to all tools (JSON-RPC 2.0 compliant)
• MCP Server Info: http://localhost:3000 - Server health and information

Development with Hot Reload

# Make scripts executable
chmod +x docker/docker-dev.sh

# Run development container
./docker/docker-dev.sh

# Or using npm scripts
npm run docker:dev

Deploy Angular UI Only

# 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 Complete System

# Deploy both MCP server and Angular UI
npm run deploy:all

# Or manually
docker compose -f docker/docker-compose.yml up -d

Verify Docker Environment

# Verify Docker setup before deployment
./docker/verify-docker.sh

# Or using npm
npm run verify:docker

For detailed Docker setup, see

🌐 Web Interface

Angular MCP Tools UI

The server includes a modern Angular-based web interface that provides:

• MCP JSON-RPC 2.0 Compliance: Full support for standardized MCP protocol
• Interactive Tool Discovery: Browse and search available tools with filtering
• Dynamic Form Generation: Automatic parameter input forms based on JSON Schema
• Real-time Tool Execution: Execute tools directly from the web interface
• Response Visualization: Formatted display of tool execution results
• Error Handling: Comprehensive error reporting and debugging information

Using the Web Interface

1. Access: Navigate to http://localhost:4200 after starting the containers
   • Note: Port 4200 is the standard Angular CLI development port
2. Discover Tools: Browse available tools by agent or category
3. Filter & Search: Use the search bar and filters to find specific tools
4. Execute Tools: Click on any tool to open the execution interface
5. View Results: See formatted responses and handle errors gracefully

MCP Protocol Support

The web interface fully implements the MCP JSON-RPC 2.0 specification:

// 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"
    }
  }
}

📋 Features

Recent Enhancements (v1.2.0)

Claude Desktop Integration:

• ✅ Native stdio support for seamless Claude Desktop integration
• ✅ Stdio-only mode (MCP_STDIO_ONLY=true) - disables HTTP server for cleaner operation
• ✅ Optimized logging - file-only logging in stdio mode
• ✅ Package bin entry - installable as a command-line tool
• ✅ Comprehensive setup guide -

Previous Enhancements (v1.1.0)

Document Agent Expansion: The Document Agent has been significantly enhanced with 22 additional tools:

• Angular UI Deployment: Complete Docker deployment configuration with multi-stage builds
• MCP JSON-RPC 2.0 Support: Full protocol compliance in both server and client
• Docker Build Fix: Changed from npm ci to npm install for Angular UI (generates package-lock.json during build)
• Angular Config Fix: Removed environment file dependencies and Angular Material references that were causing build failures
• HTML Template Fix: Fixed unterminated textarea tags in Angular component templates
• Polyfills Configuration: Added proper TypeScript compilation configuration for polyfills
• Polyfills Import Fix: Simplified polyfills.ts by removing @angular/localize/init and fixing zone.js import path
• Nginx Configuration Fix: Removed invalid 'must-revalidate' directive from gzip_proxied configuration
• UI Performance Fix: Added debounced search input and safe JSON display to prevent browser freezing
• TypeScript Fixes: Fixed NodeJS.Timeout type usage and HttpClient response type handling
• Dependency Updates: Updated Angular from v17 to v18 and suppressed npm deprecation warnings
• 22 new tools added across Priority 1-3 implementation tiers
• Enhanced API Service with PATCH method and multipart form data support
• Comprehensive error handling with proper TypeScript typing
• Advanced search capabilities with date ranges and lifecycle state filtering
• Bulk operations for efficient batch processing
• Content management with upload/download and attachment handling
• Relationship management for document linking and references

Agents

• Part Agent: Part management, BOM structures, part searches (24 tools)
• Document Agent: Comprehensive document management with 25 tools:
  • Core Lifecycle: Create, update, checkout, checkin, revise documents
  • Version Management: Version history, iterations, iteration notes
  • Content Management: Upload/download content, attachment handling
  • Relationship Management: Document references and linking
  • Advanced Search: Multi-criteria search with date/lifecycle filters
  • Bulk Operations: Batch updates and lifecycle actions
• Change Agent: Change request management (16 tools)
• Workflow Agent: Workflow items and processes (~12 tools)
• Project Agent: Project management operations (~10 tools)
• DataAdmin Agent: Container/context discovery and management (13 tools)
  • Container Discovery: List products, libraries, organizations, projects
  • Structure Navigation: Folders and folder contents
  • Configuration Management: Option pools and option sets for products/libraries
• ServerManager Agent: Multi-server management and switching (5 tools) NEW
  • Server Discovery: List all configured servers with connection details
  • Dynamic Switching: Switch between Production/Development/Test environments on-the-fly
  • Connection Testing: Test server connectivity before switching
  • Session Management: Get current server and detailed server information

Capabilities

• Session-based authentication with CSRF token management
• Automatic re-authentication on session expiry
• Comprehensive HTTP method support (GET, POST, PUT, PATCH, DELETE)
• OData query support for all endpoints with advanced filtering
• Multipart form data support for file uploads
• Extensible agent-based architecture
• Comprehensive error handling and logging
• Bulk operation support for efficient processing

🏗️ Architecture

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

🔧 Configuration

Environment Variables

📚 API Endpoints

The server uses Windchill REST API with OData endpoints:

• /ProdMgmt/Parts - Part management
• /DocMgmt/Documents - Document management
• /ChangeMgmt/ChangeRequests - Change management
• /WorkflowMgmt/WorkItems - Workflow management
• /ProjMgmt/Projects - Project management

🛠️ Development

Available Scripts

# 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

Adding New Agents

1. Create agent file in 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 */
      },
    },
  ];
}

2. Register in src/index.ts:

import { MyAgent } from "./agents/my-agent.js";

const agents = {
  // ... existing agents
  myAgent: new MyAgent(),
};

🐳 Docker Details

Production Container

• Base: Node.js 20 Alpine
• User: Non-root (nodejs:1001)
• Port: 3000
• Health Check: 30s interval

Angular UI Container

• Base: Multi-stage build (Node.js 20 + Nginx Alpine)
• Build Stage: Compiles Angular TypeScript to JavaScript using npm install
• Production Stage: Nginx serves static files with API proxy
• Port: 8080 (internal), mapped to 4200 (external)
• API Proxy: Routes /api/* requests to MCP server
• SPA Support: Handles Angular client-side routing
• Dependency Management: Generates package-lock.json during build process

Development Container

• Hot Reload: Enabled via ts-node-dev
• Source Mounting: Live code updates
• Debug Logging: Enabled

See for complete Docker documentation.

🔐 Security

• Session-based authentication with CSRF tokens
• Non-root container user
• Environment-based secrets
• Health checks enabled
• Network isolation via Docker networks

📊 Integration with Data Platform

This MCP server is part of a larger data platform architecture:

Data Sources (PLM/ERP/MES) → MCP Agents → Kafka → Data Lake → Analytics

See IT Architecture.mmd for the complete architecture diagram.

🐛 Troubleshooting

Authentication Fails

• Verify WINDCHILL_URL is accessible
• Check username/password in .env
• Ensure Windchill REST API is enabled

Container Issues

# View logs
docker-compose logs -f

# Check container status
docker-compose ps

# Restart container
docker-compose restart

Connection Issues

# Test Windchill connectivity from container
docker exec windchill-mcp-server ping plm.windchill.com

🖥️ Claude Desktop vs Web UI

This server supports two distinct usage modes:

Claude Desktop Mode (Recommended)

Use MCP_STDIO_ONLY=true for:

• ✅ Integration with Claude Desktop app
• ✅ Stdio-based MCP protocol communication
• ✅ File-only logging (no console output)
• ✅ No HTTP server overhead
• ✅ Simplified configuration

See:

Web UI Mode

Default mode with HTTP server for:

• ✅ Interactive Angular web interface on port 4200
• ✅ REST API on port 3000
• ✅ Multi-server switching capability
• ✅ Real-time tool testing
• ✅ Docker deployment support

See: Docker deployment section above

📝 License

ISC

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

📞 Support

For issues and questions:

• Check for Docker-specific issues
• Check for development guidelines
• Review logs: docker-compose logs -f