X-Readiness MCP Server

Version: 0.4.0

A Model Context Protocol (MCP) server for checking API conformance against Siemens X-API Guidelines. This tool helps developers ensure their REST APIs comply with Siemens API standards through automated planning, execution, and reporting.

Overview

This MCP server provides a structured workflow for API readiness verification:

1. Planning - Generate a checklist of rules to check based on scope and developer intent
2. Execution - Scan source code and validate against each rule systematically
3. Reporting - Generate detailed violation reports with file/line references
4. Auto-fix - Propose or apply fixes for detected violations (2-stage approval)

Features

✅ Comprehensive Rule Catalog - Based on Siemens API Guidelines (Common + REST)
✅ Scope-based Planning - Focus on specific API readiness areas
✅ Smart Rule Selection - Filters rules based on developer prompts and keywords
✅ Source Code Analysis - Scans JS/TS/JSON files for violations
✅ Detailed Violation Reports - Shows exact file paths and line numbers
✅ Approval Gates - Requires user confirmation before execution and auto-fix
✅ Markdown & JSON Output - Plans and reports in both formats
✅ Git Integration - Auto-ignores artifacts, shows diffs after fixes
✅ Two-Stage Auto-Fix - Suggest mode (preview) + Apply mode (with approval)

Artifact Storage

All tool artifacts are stored in a hidden .xreadiness/ folder in your repository:

.xreadiness/
├── plan/          # Generated plans (JSON + Markdown)
├── reports/       # Execution reports (JSON + Markdown)
└── patches/       # Auto-fix patches

The planning tool automatically adds .xreadiness/ to your .gitignore (or .git/info/exclude as fallback) to prevent committing tool artifacts.

Reference URLs

• Common API Guidelines: https://developer.siemens.com/guidelines/api-guidelines/common/index.html
• REST API Guidelines: https://developer.siemens.com/guidelines/api-guidelines/rest/index.html

Available Scopes

| Scope | Description | Categories Covered | |-------|-------------|-------------------| | x_api_readiness | Full X-API readiness check | All Common + REST Guidelines | | pagination_ready | Pagination compliance | Pagination, Sorting, Filtering, Sparse Fieldsets | | security_ready | Security compliance | Security, HTTP Protection, Error Handling | | error_handling_ready | Error handling compliance | Error Handling, Media Types, Naming | | versioning_ready | Versioning compliance | API Versioning, REST Versioning |

Workflow

Step 1: Generate a Plan

The Planning Tool analyzes your requirements and creates a high-level checklist of rules to verify.

// Example call to plan tool
{
  "tool": "plan",
  "parameters": {
    "repoPath": "/path/to/your/api/repo",
    "scope": "pagination_ready",
    "developerPrompt": "I want to check if my pagination implementation follows best practices",
    "outputFormat": "markdown"
  }
}

Output:

• Plan JSON file in mcp/plan/plan_<timestamp>_<id>.json
• Plan Markdown file in mcp/plan/plan_<timestamp>_<id>.md
• High-level checklist of rules that will be checked

Next: You'll receive the plan file path to use in execution.

Step 2: Execute the Plan (Requires Approval)

The Execution Tool scans your source code and checks each rule systematically.

First Call (Request Approval):

{
  "tool": "execute",
  "parameters": {
    "repoPath": "/path/to/your/api/repo",
    "planPath": "/path/to/plan_<timestamp>_<id>.json"
  }
}

Response:

{
  "status": "CONFIRMATION_REQUIRED",
  "message": "⚠️ APPROVAL REQUIRED: Execution will scan your source code...",
  "approvalCode": "123456",
  "expires_in_minutes": 10
}

Second Call (With Approval Code):

{
  "tool": "execute",
  "parameters": {
    "repoPath": "/path/to/your/api/repo",
    "planPath": "/path/to/plan_<timestamp>_<id>.json",
    "approvalCode": "123456"
  }
}

Output:

• Execution report JSON in mcp/reports/run_<timestamp>_<id>.json
• Execution report Markdown in mcp/reports/run_<timestamp>_<id>.md
• Detailed violation table with file paths and line numbers

Step 3: Review Violations

The execution report includes:

• Summary - Pass/fail/skipped rule counts
• Violation Table - All violations with:
  • Rule ID
  • Category
  • Severity
  • File path
  • Line number
  • Violation message
  • Guideline reference link
• Violations by File - Grouped view of all issues per file

Step 4: Auto-Fix (Optional, Requires Approval)

The Auto-fix Tool can propose or apply fixes for detected violations.

First Call (Request Approval):

{
  "tool": "auto_fix",
  "parameters": {
    "repoPath": "/path/to/your/api/repo",
    "runId": "run_<timestamp>_<id>",
    "mode": "propose"
  }
}

Modes:

• propose - Shows proposed fixes without modifying files
• apply - Applies fixes directly to source code

Rule Categories

The master template includes rules across these categories:

1. PAGINATION (Priority: High) - 8 rules
2. ERROR_HANDLING (Priority: Critical) - 11 rules
3. MEDIA_TYPES (Priority: High) - 18 rules
4. NAMING_CONVENTIONS (Priority: Medium) - 8 rules
5. SECURITY (Priority: Critical) - 9 rules
6. VERSIONING (Priority: Medium) - 8 rules
7. COMMON_OPERATIONS (Priority: High) - 5 rules
8. BULK_OPERATIONS (Priority: Medium) - 2 rules
9. FILTERING (Priority: Medium) - 3 rules
10. SORTING (Priority: Low) - 4 rules
11. SPARSE_FIELDSETS (Priority: Low) - 2 rules

Total: ~80 rules

Implemented Rule Checkers

Currently implemented checkers (v0.5.0):

• ✅ Pagination Rules - Checks for pagination links, cursor/offset/index strategies
• ✅ Error Handling Rules - Validates HTTP status codes, error object structure, stack trace exposure
• ✅ Naming Convention Rules - Checks camelCase, snake_case, ASCII characters
• ✅ Security Rules - Validates OAuth/Bearer tokens, HTTPS usage

Coming Soon:

• Media Types validation
• Versioning compliance checks
• Operations (CRUD) validation
• Filtering/Sorting/Sparse fieldsets validation

Installation

cd mcp
npm install

Usage

Start the MCP Server

npm start

Use with MCP Client

Configure your MCP client (e.g., Claude Desktop, VS Code) to connect to this server.

Example mcp.json configuration:

{
  "mcpServers": {
    "x-readiness": {
      "command": "node",
      "args": ["c:/Users/z004mbbk/Projects/conformance-X/mcp/server.js"],
      "cwd": "c:/Users/z004mbbk/Projects/conformance-X/mcp"
    }
  }
}

Example Workflow

Developer: "Check my API for pagination readiness"

1. AI calls 'plan' tool
   → Generates plan with pagination-related rules
   → Saves to mcp/plan/plan_2026-02-02_abc123.json

2. AI informs user: "Plan generated. Ready to execute?"

3. User: "Yes, proceed"

4. AI calls 'execute' tool (without approval code)
   → Receives approval code: 123456

5. AI asks user: "Execution requires approval. Code: 123456. Proceed?"

6. User: "Yes"

7. AI calls 'execute' tool (with approval code)
   → Scans source code
   → Checks each pagination rule
   → Generates violation report

8. AI presents results:
   "Found 5 violations:
    - api/users.js:42 - Missing pagination links
    - api/orders.js:78 - No cursor pagination meta
    ..."

9. User: "Can you fix these?"

10. AI calls 'auto_fix' tool
    → Proposes fixes
    → Waits for approval

Directory Structure

mcp/
├── server.js              # Main MCP server
├── package.json
├── README.md              # This file
├── bin/
│   └── cli.js            # CLI entry point
├── tools/
│   ├── planning.js       # Planning tool implementation
│   ├── execution.js      # Execution tool implementation
│   ├── autofix.js        # Auto-fix tool implementation
│   ├── template-parser.js # Master template parser
│   └── rule-checkers.js  # Rule evaluation logic
├── templates/
│   └── master_template.md # Rule catalog (80+ rules)
├── plan/                  # Generated plans (created on first use)
│   └── plan_*.json
│   └── plan_*.md
└── reports/               # Execution reports (created on first use)
    └── run_*.json
    └── run_*.md

Development

Adding New Rule Checkers

To add a checker for a new rule category:

1. Edit tools/rule-checkers.js
2. Add a new checker function (e.g., checkMediaTypesRule)
3. Update the checkRule routing logic
4. Implement violation detection logic

Updating the Master Template

The master template (templates/master_template.md) is the source of truth for all rules. To add new rules:

1. Add rules under the appropriate category
2. Follow the format: - RULE_ID: Rule description
3. The template parser will automatically pick up changes

License

This tool is based on Siemens API Guidelines and is intended for internal use to ensure API compliance.

Support

For issues or questions, refer to:

• Siemens API Guidelines: https://developer.siemens.com/guidelines/api-guidelines/
• Internal MCP documentation

Built with ❤️ for X-API Readiness