graph TB
    subgraph "MCP Clients"
        Claude["Claude / Cursor / Agent"]
        Inspector["MCP Inspector"]
        UI["React Frontend :3000"]
    end

    subgraph "Transport"
        Stdio["StdioServerTransport\n(Smithery / Inspector)"]
        Bridge["Express API :5000\nSDK Client + StdioClientTransport"]
    end

    subgraph "MCP Server  —  index.js  v3.0.0"
        McpSrv["McpServer\nspec 2025-11-25"]
        Tools["7 Tools\nZod · annotated"]
        Resources["4 Resources\nKB articles · Tickets"]
        Prompts["3 Prompts\nIncident · Status · KB-assist"]
        Store["In-Memory Store\nTickets & KB articles"]
    end

    subgraph "Backend Services"
        Auth["JWT Auth"]
        Metrics["Metrics Store"]
        Mongo[("MongoDB")]
    end

    Claude -->|stdio| Stdio
    Inspector -->|stdio| Stdio
    UI -->|HTTP + JWT| Bridge

    Stdio --> McpSrv
    Bridge -->|"MCP SDK Client\n(proper handshake)"| McpSrv

    McpSrv --> Tools
    McpSrv --> Resources
    McpSrv --> Prompts
    Tools <--> Store
    Resources --> Store

    Bridge --> Auth
    Bridge --> Metrics
    Auth --> Mongo

sequenceDiagram
    participant U as User
    participant UI as React UI :3000
    participant API as Express API :5000
    participant C as MCP SDK Client
    participant MCP as McpServer index.js

    U->>UI: Submit form
    UI->>API: POST /api/mcp/tools/call (JWT)
    API->>C: client.callTool(name, args)
    Note over C: StdioClientTransport
    C->>MCP: tools/call (MCP protocol)
    Note over MCP: Zod validates input
    MCP->>MCP: tool handler + in-memory store
    MCP-->>C: CallToolResult
    C-->>API: result
    API->>API: recordCall() → metrics
    API-->>UI: { success, data, _meta }
    UI->>U: Show result

# Root (MCP server)
npm install

# Backend API
cd backend && npm install && cd ..

# Frontend
cd frontend && npm install && cd ..

cp .env.example .env          # root — API key for Smithery / MCP auth
cp backend/.env.example backend/.env   # backend — Mongo URI, JWT secret, ITSM creds

MONGODB_URI=mongodb://localhost:27017/mcp-itsm
JWT_SECRET=change-me-in-production

# Terminal 1 — MCP server (stdio)
npm start

# Terminal 2 — Backend API
cd backend && npm start        # http://localhost:5000

# Terminal 3 — Frontend
cd frontend && npm start       # http://localhost:3000

flowchart LR
    T1["Terminal 1\nnpm start\nMCP server on stdio"]
    T2["Terminal 2\ncd backend\nnpm start  :5000"]
    T3["Terminal 3\ncd frontend\nnpm start  :3000"]
    UI["localhost:3000\nTicket Manager\nMonitor Dashboard"]

    T1 -->|"SDK Client\nStdioClientTransport"| T2
    T2 -->|"HTTP + JWT"| T3
    T3 --> UI

mcp-itsm/
├── index.js                  # MCP server (McpServer, Zod, stdio)
├── tools.json                # Static tool catalogue for Smithery browser
├── smithery.yaml             # Smithery deployment config
├── package.json              # Root deps: @modelcontextprotocol/sdk, zod
├── .env.example              # Root env template
│
├── backend/
│   ├── package.json          # Express, Mongoose, JWT, MCP SDK Client
│   ├── .env.example          # Backend env template
│   └── src/
│       ├── index.js          # Express app bootstrap
│       ├── config/config.js  # Env-driven configuration
│       ├── routes/
│       │   ├── mcp.routes.js      # MCP bridge + metrics endpoints
│       │   ├── auth.routes.js
│       │   ├── context.routes.js
│       │   ├── integration.routes.js
│       │   └── user.routes.js
│       ├── middleware/
│       │   ├── auth.middleware.js
│       │   └── validation.middleware.js
│       ├── models/
│       ├── validators/
│       └── utils/logger.js
│
├── frontend/
│   ├── package.json          # React 18, Bootstrap, react-router-dom
│   └── src/
│       ├── App.js
│       ├── pages/
│       │   ├── MCPTicketManager.js     # Ticket CRUD UI
│       │   ├── MCPMonitorDashboard.js  # Live monitoring (polls every 10s)
│       │   ├── Dashboard.js
│       │   ├── LLMChatClient.js
│       │   └── ...
│       ├── services/
│       │   ├── mcpService.js   # HTTP client for MCP tool calls
│       │   └── api.js          # Axios instance with JWT interceptor
│       └── components/
│           ├── Header.js
│           └── ...
│
└── docs/
    ├── api-documentation.md
    ├── mcp_relationship.md
    └── llm_enabled_tickets.md

graph LR
    subgraph RO["Read-only  —  safe to call freely"]
        GT["get_ticket\nreadOnly · idempotent"]
        LT["list_tickets\nreadOnly · idempotent"]
        SK["search_knowledge_base\nreadOnly · idempotent"]
    end
    subgraph WR["Write  —  require user intent"]
        CT["create_ticket\nwrite"]
        UT["update_ticket\nwrite"]
        AT["assign_ticket\nwrite · idempotent"]
        AC["add_comment\nwrite"]
    end
    style RO fill:#f0fdf4,stroke:#86efac
    style WR fill:#fff1f2,stroke:#fecdd3

// Tool call
{
  "name": "create_ticket",
  "arguments": {
    "title": "VPN not connecting after Windows update",
    "description": "Since the KB5034441 update, VPN client fails to authenticate on first attempt.",
    "priority": "high",
    "system": "jira"
  }
}

// Response
{
  "success": true,
  "ticket": {
    "id": "JIRA-1000",
    "title": "VPN not connecting after Windows update",
    "system": "jira",
    "status": "open",
    "priority": "high",
    "url": "https://example.com/jira/tickets/JIRA-1000"
  }
}

graph LR
    McpSrv["McpServer"]
    McpSrv -->|"static\nkb://articles"| KBAll["kb-articles\nAll KB articles as JSON"]
    McpSrv -->|"template\nkb://articles/{id}"| KBOne["kb-article\nSingle article by ID"]
    McpSrv -->|"static\nitsm://tickets/open"| TOpen["open-tickets\nLive filtered view"]
    McpSrv -->|"template\nitsm://tickets/{id}"| TOne["ticket\nSingle ticket by ID"]
    style McpSrv fill:#f0fdf4,stroke:#86efac

sequenceDiagram
    participant U as User
    participant C as MCP Client
    participant MCP as McpServer

    U->>C: "My printer won't install"
    C->>MCP: prompts/get  kb-search-assist
    MCP-->>C: message template
    C->>MCP: tools/call  search_knowledge_base
    MCP-->>C: KB-005 Printer setup guide
    C->>U: Show article — no ticket needed
    Note over C,U: Only escalates to create_ticket if no article resolves it

# API key used when running via Smithery (injected as API_KEY env var)
API_KEY=your-smithery-api-key

# ServiceNow live adapter (optional — leave unset to keep system=servicenow
# calls on the in-memory mock). See "ServiceNow Live Adapter" below.
SERVICENOW_BASE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=
SERVICENOW_PASSWORD=

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/mcp-itsm

# Auth
JWT_SECRET=change-me-to-a-long-random-string
JWT_EXPIRES_IN=1d

# ITSM integrations reserved for future backend-level adapters. Only the
# ServiceNow adapter is implemented so far, and it reads its credentials
# from root `.env` (above), not from here — these are unused placeholders
# until adapters move into the backend or the other systems get one too.
SERVICENOW_BASE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=

ZENDESK_BASE_URL=https://your-org.zendesk.com
ZENDESK_USERNAME=you@example.com
ZENDESK_TOKEN=

IVANTI_BASE_URL=https://your-instance.ivanti.com
IVANTI_CLIENT_ID=
IVANTI_CLIENT_SECRET=

CHERWELL_BASE_URL=https://your-instance.cherwell.com
CHERWELL_CLIENT_ID=
CHERWELL_USERNAME=
CHERWELL_PASSWORD=

# Logging
LOG_LEVEL=info

flowchart TD
    DB["React Dashboard\n/mcp-monitor\npoll every 10 s"]
    DB -->|"GET /api/mcp/health"| H["connected · uptimeSeconds"]
    DB -->|"GET /api/mcp/metrics"| M["totalCalls · successRate\ntoolStats · recentCalls"]
    DB -->|"GET /api/mcp/tools/list"| T["tool names + annotations"]
    DB -->|"GET /api/mcp/resources/list"| R["resource URIs"]
    DB -->|"GET /api/mcp/prompts/list"| P["prompt names"]

# Authenticate first
TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}' | jq -r '.token')

# Call a tool
curl -X POST http://localhost:5000/api/mcp/tools/call \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_knowledge_base",
    "arguments": { "query": "vpn", "limit": 3 }
  }'

flowchart LR
    Dev["Developer\nnpm publish via\nsmithery publish"]
    Smithery["Smithery Cloud\nDocker container\nenv API_KEY injected"]
    MCPSrv["McpServer v3.0.0\nnpm start → stdio"]
    Client["Claude / Cursor\nany MCP client"]

    Dev -->|"smithery.yaml\ntools.json"| Smithery
    Smithery -->|"spawn"| MCPSrv
    Client -->|"MCP protocol\nstdio"| Smithery
    Smithery <-->|"proxy"| MCPSrv

npx -y @smithery/cli install @madosh/mcp-itsm --client claude

npm install -g @smithery/cli
smithery login
smithery publish

startCommand:
  type: stdio
  configSchema:
    type: object
    required: [apiKey]
    properties:
      apiKey:
        type: string
  commandFunction: |-
    (config) => ({ command: 'npm', args: ['start'], env: { API_KEY: config.apiKey } })
tools:
  path: ./tools.json

{
  "mcpServers": {
    "mcp-itsm": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-itsm/index.js"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

npm run debug-mcp
# Opens MCP Inspector at http://localhost:5173

# Root
npm start              # Start MCP server on stdio
npm run debug-mcp      # Start with MCP Inspector attached

# Backend
cd backend
npm start              # Production
npm run dev            # Development (nodemon hot-reload)
npm test               # Jest test suite

# Frontend
cd frontend
npm start              # Dev server on :3000
npm run build          # Production build

docker build -t mcp-itsm .
docker run -e API_KEY=your-key mcp-itsm

graph LR
    subgraph Done["Shipped in v3.0.0"]
        D1["SDK 1.28.0 + Zod"]
        D2["McpServer API"]
        D3["Tool annotations"]
        D4["Resources + Prompts"]
        D5["SDK Client transport"]
        D6["Metrics + Dashboard"]
        D7["ServiceNow live adapter"]
    end
    subgraph Next["Next"]
        N1["OAuth 2.1 / OIDC"]
        N2["Elicitation"]
        N3["Tasks API"]
        N4["Jira/Zendesk/Ivanti/Cherwell live adapters"]
        N5["CMDB support"]
    end
    style Done fill:#f0fdf4,stroke:#86efac
    style Next fill:#eff6ff,stroke:#bfdbfe