Siemens Acronyms MCP Server

📚 Dual Purpose Project

This repository serves two important audiences:

1. MCP Server Example

For developers adding MCP (Model Context Protocol) to existing REST APIs without separate server binaries. This demonstrates how to make institutional knowledge accessible to AI assistants and development tools.

2. Compound Engineering Scaffold

For developers adopting AI-assisted workflows with Claude Code and other AI tools. A complete project structure optimized for parallel task execution and AI orchestration.

🎬 Watch the workflow: Compound Engineering with Claude Code (15 min)
📋 Fork the scaffold: See SCAFFOLD_NOTES.md for reusing this structure

🏗️ The Method: Compound Engineering

This scaffold implements the workflow from Kieran Klaassen's Claude Code: How Two Engineers Ship Like a Team of 15.

Two engineers at Every shipped 6 features, 5 bug fixes, and 3 infrastructure updates in one week. How? By using GitHub issues + AI in a way that makes every line of code traceable to requirements.

Why It Works for Enterprise Teams

You already use GitHub/GitLab issues
Everything is transparent: Issues → Kanban → PRs
No "vibe coding" - every change has a clear purpose
No new tools to learn, just better use of existing ones

Real Example: This Repository

Built entirely with this approach. Check our public Kanban board to see how PRs #7 and #9 went from issue to deployment.

Learn More

📺 Original video (74K+ views)
📖 Detailed article by Every
🎬 15-min demo
📋 My story: SCAFFOLD_NOTES.md

Overview

A glossary service exposing Siemens-specific terminology via REST API and MCP endpoints. This working example demonstrates modern MCP best practices that solve real integration problems.

🎯 See It In Action

One MCP server, multiple AI assistants: The same Siemens glossary seamlessly integrates with Claude Code's CLI for automation and VS Code's GitHub Copilot for interactive development.

✨ Key Features

Dual Protocol Support: REST API for web apps, MCP for AI assistants
Fuzzy Search: Handles typos like "Temcenter" → "Teamcenter"
Multi-Client: Works with Claude Code CLI, VS Code, and any MCP client
Hot Reload: Update glossary without restarting server
Secure: API key authentication for MCP endpoints
Fast: <50ms response time with 1000+ terms

🎯 Why This MCP Implementation is Different

This server demonstrates modern MCP best practices that solve real integration problems:

✅ No Azure AD Overhead

Simple API key management via MCP_API_KEYS environment variable
Perfect for small teams who want to manage their own authentication
No complex OAuth flows or enterprise identity provider setup required

✅ VS Code Compatible Authentication

Uses HTTP 403 Forbidden (not 401 Unauthorized) for invalid API keys
Prevents "Dynamic Client Registration not supported" OAuth popup errors
Maintains security without breaking the VS Code user experience

✅ Proper FastMCP Usage

Actually uses @mcp.tool() decorators (doesn't define them and ignore them)
Clean 150-line implementation vs typical 300+ line manual JSON-RPC handling
FastMCP handles all protocol details automatically

✅ Production Ready

Middleware-based authentication with proper error handling
Separate service modules for clean code organization
Comprehensive test coverage with modern pytest patterns

🚀 Quick Start

Prerequisites

Python 3.10 or higher
pip package manager
FastMCP 2.11.2 or higher (older versions have different API)

Prerequisites Check:

# Verify Python version (should be 3.10+)
python --version

# Verify pip is installed and recent
python -m pip --version

# Upgrade pip to latest (recommended)
python -m pip install --upgrade pip

Installation

Clone the repository

git clone <repository-url>
cd siemens-acronyms-mcp

Set up Python virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Verify Installation:

# Check FastMCP version (should be 2.11.2+)
python -c "import fastmcp; print(f'FastMCP version: {fastmcp.__version__}')"

# Verify all dependencies installed
python -c "import fastapi, starlette, rapidfuzz; print('All dependencies OK')"

Configure environment variables

cp env.example .env

Edit .env and add your API keys:

# Comma-separated list of API keys for MCP endpoint authentication
MCP_API_KEYS=sk-team-A,sk-team-B,sk-Daniel

# Optional: Custom path to acronyms file
# GLOSSARY_FILE_PATH=siemens_acronyms.json

# Optional: Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

Run the server
```
uvicorn src.main:app --reload --port 8000
```
The server will be available at http://localhost:8000

Quick Test Your Setup

After starting the server, verify everything is working:

# Test 1: Health endpoint
curl http://localhost:8000/health
# Expected: {"status":"healthy","hostname":"...","uptime":...,"version":"1.0.0"}

# Test 2: REST API search
curl "http://localhost:8000/api/v1/search?q=EDA"
# Expected: Results with EDA definition

# Test 3: Fuzzy search (handles typos)
curl "http://localhost:8000/api/v1/search?q=Temcenter"
# Expected: Returns "Teamcenter" with ~94% match score

# Test 4: MCP via Claude Code (if configured)
claude -p "Using the siemens-acronyms MCP server, what does DISW mean?"
# Expected: Returns DISW definition

What's Included

siemens-acronyms-mcp/
├── src/
│   ├── main.py              # FastAPI server (150 lines, clean & focused)
│   ├── mcp_service.py       # MCP tools using proper @mcp.tool() decorators  
│   ├── auth_middleware.py   # HTTP 403 auth (VS Code compatible)
│   └── acronyms_service.py  # Fuzzy search engine with file watching
├── tests/
│   └── test_acronyms_server.py  # Modern pytest test suite
├── siemens_acronyms.json    # Glossary data (3 samples, add more!)
├── .vscode/
│   ├── mcp.json            # VS Code MCP configuration (works without OAuth!)
│   └── settings.json       # Development settings
├── .claude/
│   └── settings.json       # Claude Code permissions
└── assets/
    └── MCP_demo_*.png      # Working demo screenshot

📡 API Endpoints

1. REST API (Public Access)

Search Endpoint: GET /api/v1/search?q={query}

No authentication required. Returns acronym definitions with fuzzy matching.

# Search for an exact acronym
curl "http://localhost:8000/api/v1/search?q=EDA"

# Fuzzy search handles typos
curl "http://localhost:8000/api/v1/search?q=Temcenter"
# Returns: Teamcenter (with similarity score)

# Partial matches
curl "http://localhost:8000/api/v1/search?q=Sim"
# Returns: Simcenter and related terms

Response format:

{
  "results": [
    {
      "term": "EDA",
      "full_name": "Electronic Design Automation",
      "description": "IC design, PCB design, and electronic systems design tools",
      "score": 100.0
    }
  ],
  "query": "EDA",
  "count": 1
}

2. MCP Endpoint (Protected)

Endpoint: POST /mcp

Requires X-API-Key header with valid API key from MCP_API_KEYS (except for the get_health tool).

📝 Important: This implementation uses HTTP 403 Forbidden for authentication failures (not 401 Unauthorized). This prevents VS Code from triggering OAuth popups and maintains a smooth user experience while keeping your data secure.

Available MCP Tools:

search_acronyms - Search for Siemens acronyms and terminology
- Parameters: query (string, required)
- Returns: Matching terms with fuzzy search support
- Authentication: Required
get_health - Get server health status
- Parameters: None
- Returns: Server status, hostname, uptime, and version
- Authentication: Not required (public tool)

# List available tools
curl -X POST http://localhost:8000/mcp \
  -H "X-API-Key: sk-team-A" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Search using MCP protocol (requires authentication)
curl -X POST http://localhost:8000/mcp \
  -H "X-API-Key: sk-team-A" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_acronyms",
      "arguments": {"query": "DISW"}
    },
    "id": 2
  }'

# Get health status via MCP (no authentication required)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_health",
      "arguments": {}
    },
    "id": 3
  }'

3. Health Check

Endpoint: GET /health

curl http://localhost:8000/health

Returns:

{
  "status": "healthy",
  "hostname": "your-hostname",
  "uptime": 123.45,
  "version": "1.0.0"
}

4. API Documentation

Interactive Swagger UI available at: http://localhost:8000/docs

🤖 Connecting AI Assistants via MCP

Claude Code Integration

After starting the server, you can connect Claude Code to use the acronyms service:

Add the MCP Server

# Add the MCP server with HTTP transport and API key
claude mcp add --transport http siemens-acronyms http://localhost:8000/mcp \
  --header "X-API-Key: sk-team-A"

# Verify connection status (should show ✓ Connected)
claude mcp list

Option 2: Manual Configuration in .mcp.json

Create or edit .mcp.json in your project directory (for local scope) or use claude mcp add --scope project for team sharing:

{
  "mcpServers": {
    "siemens-acronyms": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "sk-team-A"
      }
    }
  }
}

Or with environment variable expansion:

{
  "mcpServers": {
    "siemens-acronyms": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "${MCP_API_KEY:-sk-team-A}"
      }
    }
  }
}

Verify Configuration

# List configured MCP servers
claude mcp list

# Get details of the siemens-acronyms server
claude mcp get siemens-acronyms

Interactive Usage in Claude Code

After configuration, in Claude Code you can ask:
- "What does DISW mean in Siemens context?"
- "Search for EDA in the Siemens glossary"
- "Find information about Teamcenter"
- "Use the siemens-acronyms MCP server to search for TeamCenter"

Non-Interactive Usage (Command Line)

Use the -p flag for non-interactive queries, perfect for scripts and automation:

# Basic search
claude -p "Using the siemens-acronyms MCP server, what does DISW mean?"

# Test fuzzy matching (handles typos)
claude -p "Using the siemens-acronyms MCP server, search for 'Temcenter'"
# Returns: Teamcenter with 94.74% match score

# Search by partial terms
claude -p "Using the siemens-acronyms MCP server, search for 'software'"
# Returns: DISW and other software-related acronyms

# With permission bypass for automation
claude -p --dangerously-skip-permissions \
  "Using the siemens-acronyms MCP server, what does EDA stand for?"

Note: Claude Code will request permission to use MCP tools on first use. Either:

Grant permission interactively when prompted
Use --dangerously-skip-permissions flag for scripts (use cautiously)
Configure allowed tools in .claude/settings.json

VS Code with GitHub Copilot Chat

VS Code v1.103+ includes native MCP support integrated with GitHub Copilot Chat.

Setup Instructions

Important for WSL2/Windows Users: If running VS Code on Windows with the server in WSL2, use the User Configuration method below.

Start the MCP server (in WSL2 or terminal):
```
uvicorn src.main:app --reload --port 8000
```
Configure in VS Code (choose one method):

Method A: Via UI (Easier)
- Open Command Palette (Ctrl+Shift+P)
- Run: MCP: Add Server
- Enter server details when prompted
- VS Code will save configuration automatically
Method B: Edit Configuration File
- Open Command Palette (Ctrl+Shift+P)
- Run: MCP: Open User Configuration
- Add this configuration:
```
{
  "servers": {
    "siemens-acronyms": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "sk-team-A"
      }
    }
  }
}
```
- Save and reload VS Code
Start and verify the server:
- Command Palette → MCP: Show Installed Servers
- Click "Start" next to siemens-acronyms
- Should show "Running" status
Use in GitHub Copilot Chat:
- Open Copilot Chat (Ctrl+I)
- Switch to "Agent" mode (click agent icon)
- Test: "What does DISW mean?"
- The tool search_acronyms will be invoked automatically

Note: Windows automatically forwards localhost:8000 from WSL2, so no special network configuration is needed.

🔍 Real-World Usage Examples

Based on practical testing with Claude Code, here are actual results:

Fuzzy Matching in Action

# Typo in "Teamcenter" → Still finds the right result
$ claude -p --dangerously-skip-permissions \
    "Using siemens-acronyms MCP, search for 'Temcenter'"
> Found "Teamcenter" with 94.74% confidence score

# Partial word matching
$ claude -p --dangerously-skip-permissions \
    "Using siemens-acronyms MCP, search for 'software'"
> Found DISW (Digital Industries Software) with 84% match

Understanding MCP Communication

Each Claude Code query triggers multiple MCP calls:

initialize - Protocol handshake
tools/list - Discover available tools
tools/call - Execute the search
Server logs show all requests with 200 OK status

Performance Observations

Response time: <50ms for typical queries
Connection overhead: ~100ms for initial handshake
Fuzzy matching adds negligible latency (<10ms)

🧪 Testing

Run the comprehensive test suite:

# Run all tests
pytest -v

# Run with coverage report
pytest -v --cov=src

# Run specific test categories
pytest -v tests/test_acronyms_server.py::TestRESTEndpoint
pytest -v tests/test_acronyms_server.py::TestMCPEndpoint

Current test coverage: 83% with 31 tests passing.

🔧 Development

Project Structure

siemens-acronyms-mcp/
├── src/
│   ├── main.py              # FastAPI application
│   └── acronyms_service.py  # Core search service
├── tests/
│   └── test_acronyms_server.py  # Test suite
├── siemens_acronyms.json    # Glossary data (hot-reloadable)
├── requirements.txt         # Python dependencies
├── env.example            # Environment template
└── README.md              # This file

Adding New Acronyms

Edit siemens_acronyms.json:

{
  "acronyms": [
    {
      "term": "NEW_TERM",
      "full_name": "Full Name of Term",
      "category": "Acronym",
      "description": "Description of what this term means",
      "division": "DISW",
      "url": "https://optional-url.com",
      "related": ["RELATED1", "RELATED2"]
    }
  ]
}

The service automatically reloads the file without restart.

Code Quality

Before committing:

# Format code
ruff format .

# Check linting
ruff check . --fix

# Run tests
pytest -v

🚦 Deployment

Production Deployment

Using Uvicorn directly

uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4

Using Gunicorn with Uvicorn workers

gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Docker deployment

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment Variables

Variable	Description	Default	Required
`MCP_API_KEYS`	Comma-separated API keys for MCP auth	-	Yes (for MCP)
`GLOSSARY_FILE_PATH`	Path to acronyms JSON file	`siemens_acronyms.json`	No
`LOG_LEVEL`	Logging level	`INFO`	No

📊 Performance

Search response time: <100ms for 1000+ terms
Concurrent requests: Handles 50+ simultaneous connections
Memory usage: ~50MB with 1000 terms loaded
Hot reload: File changes detected within 1 second

🤝 Contributing

Check existing issues or create new ones
Follow TDD approach - write tests first
Ensure all tests pass and code is formatted
Update siemens_acronyms.json for new terms
Create pull request with clear description

📄 License

Source Code: MIT License - Use freely in your projects
Glossary Data: CC BY 4.0 - Share and adapt with attribution

This dual licensing allows both internal Siemens use and external contributions.

🆘 Troubleshooting

Server won't start

Check Python version: python --version (needs 3.10+)
Verify all dependencies: pip install -r requirements.txt
Check port availability: lsof -i :8000

MCP endpoint returns 401

Verify API key in .env file
Check X-API-Key header in request
Ensure no spaces in MCP_API_KEYS value

Search returns no results

Check siemens_acronyms.json file exists and is valid JSON
Verify file permissions allow reading
Check logs for file loading errors

Claude Code can't connect

Ensure server is running: curl http://localhost:8000/health
Verify API key matches between server and client config
Check firewall/network settings allow localhost connections
Protocol version issue: Claude Code uses "2025-06-18" protocol version
- The server automatically echoes back the client's requested version
- If you see connection success but tools don't work, restart Claude Code

📞 Support

For issues or questions:

Check the Issues page
Review test files for usage examples
Consult CLAUDE.md for AI assistant guidance

Note: This is a demonstration project showing how to MCP-enable internal glossaries and APIs. The patterns shown here can be applied to other internal services to make them accessible to AI assistants while maintaining security through API key authentication.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.claude		.claude
.github		.github
.vscode		.vscode
analysis		analysis
assets		assets
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GITHUB_ACTIONS_SETUP.md		GITHUB_ACTIONS_SETUP.md
README.md		README.md
SCAFFOLD_NOTES.md		SCAFFOLD_NOTES.md
env.example		env.example
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
siemens_acronyms.json		siemens_acronyms.json

dzivkovi/siemens-acronyms-mcp

Folders and files

Latest commit

History

Repository files navigation