┌─────────────────────────────────────────────────────────────────────────┐
│                        MCP Tool Manager Platform                        │
│                                                                         │
│  ┌──────────────────────┐        ┌────────────────────────────────────┐ │
│  │   Manager Server      │        │    Hardened MCP Server             │ │
│  │   src/server          │        │    mcp-server-project              │ │
│  │                       │        │                                    │ │
│  │  • REST API (CRUD)    │        │  • MCP Protocol endpoint           │ │
│  │  • JWT + API key auth │        │  • Agent API key auth + expiry     │ │
│  │  • Tool registry      │        │  • Circuit breaker per tool        │ │
│  │  • Agent management   │        │  • Retry + exponential backoff     │ │
│  │  • Credential vault   │        │  • Response cache (TTL per tool)   │ │
│  │  • Audit log          │        │  • Context window limiting         │ │
│  │  • State snapshots    │        │  • File-persisted call log         │ │
│  │  • WebSocket events   │        │  • 10-family threat detection      │ │
│  │  • Response cache     │        │  • Admin /metrics endpoint         │ │
│  └──────────┬───────────┘        └──────────────┬─────────────────────┘ │
│             │                                    │                       │
│  ┌──────────▼───────────┐        ┌──────────────▼─────────────────────┐ │
│  │   React Dashboard     │        │    Claude Desktop / LLM Agent      │ │
│  │   src/dashboard       │        │    (connects via MCP SDK)          │ │
│  └──────────────────────┘        └────────────────────────────────────┘ │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │  Cross-cutting: X-Trace-ID · Rate Limiting · Helmet CSP ·        │   │
│  │  Structured Logging · Connection Limit · Compression             │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

mcp/
├── .env.example                    # Template — copy to .env and fill in values
├── .gitignore                      # Excludes .env, node_modules, logs, snapshots
├── package.json                    # Root scripts — start both servers, CLI, tests
├── README.md                       # This file
├── REPORT.md                       # Full technical capability report
├── CHANGELOG.md                    # Version history
│
├── src/
│   ├── server/                     # Manager Server (REST API)
│   │   ├── index.js                # Entry point — snapshot restore + server start
│   │   ├── app.js                  # Express app — all middleware wired
│   │   ├── routes/
│   │   │   ├── tools.js            # CRUD + test execution for tools
│   │   │   ├── agents.js           # Agent management + tool discovery
│   │   │   ├── auth.js             # Login, register, API key management
│   │   │   ├── credentials.js      # Encrypted credential vault
│   │   │   └── monitoring.js       # Stats, audit log, cache, snapshot status
│   │   ├── middleware/
│   │   │   ├── auth.js             # JWT + API key auth + RBAC
│   │   │   └── error-handler.js    # Typed errors + global handler
│   │   ├── storage/
│   │   │   ├── in-memory-store.js  # All in-memory Maps + operations
│   │   │   ├── seeder.js           # Initial data (skipped if snapshot exists)
│   │   │   └── state-snapshot.js   # Periodic disk snapshots (JSON files)
│   │   ├── utils/
│   │   │   ├── trace.js            # X-Trace-ID middleware
│   │   │   ├── context-limit.js    # Response byte budget + pagination guard
│   │   │   ├── response-cache.js   # node-cache wrapper + TTL presets
│   │   │   ├── encryption.js       # AES-256-CBC for credential vault
│   │   │   └── logger.js           # Levelled logger (error/warn/info/debug)
│   │   └── websocket.js            # Real-time events via WebSocket
│   │
│   ├── dashboard/                  # React + Vite management UI
│   │   ├── src/
│   │   │   ├── pages/              # Dashboard, Tools, Agents, Monitoring, Settings
│   │   │   ├── components/         # Sidebar, Topbar, ToastContainer
│   │   │   ├── services/api.js     # Axios client for Manager Server
│   │   │   └── styles/             # global.css, sidebar.css
│   │   └── vite.config.js
│   │
│   ├── sdk/
│   │   └── index.js                # Developer SDK — npm-publishable client
│   │
│   └── cli/
│       └── index.js                # Admin CLI (17 commands)
│
├── mcp-server-project/             # Hardened MCP Server
│   ├── package.json
│   ├── src/
│   │   ├── server.js               # Boot sequence — all 7 security layers
│   │   ├── mcp-protocol.js         # MCP spec endpoint (/mcp/tools, /mcp/invoke)
│   │   ├── routes/
│   │   │   ├── invoke.js           # Tool invocation (retry + CB + cache + limit)
│   │   │   ├── info.js             # Tool discovery per agent
│   │   │   └── metrics.js          # Admin monitoring endpoint
│   │   ├── middleware/
│   │   │   ├── auth.js             # Agent auth + expiry + scope + disabled check
│   │   │   ├── trace.js            # X-Trace-ID attachment
│   │   │   └── context-limit.js    # Response byte budget
│   │   ├── state/
│   │   │   ├── call-log.js         # Disk-persisted call log (NDJSON)
│   │   │   ├── circuit-breaker.js  # Per-tool CLOSED/OPEN/HALF state machine
│   │   │   └── response-cache.js   # TTL cache with auto-eviction
│   │   ├── loaders/
│   │   │   ├── registry.js         # Central tool+agent in-memory registry
│   │   │   ├── tool-loader.js      # Loads *.json from /tools/
│   │   │   ├── agent-loader.js     # Loads *.json from /agents/
│   │   │   └── credential-loader.js # Merges .env + JSON credentials
│   │   └── watcher.js              # chokidar hot-reload on /tools/ and /agents/
│   ├── security/
│   │   ├── middleware/
│   │   │   ├── security-headers.js # Strict Helmet CSP + CORS
│   │   │   ├── rate-limiter.js     # 3-tier rate limiting + IP auto-block
│   │   │   └── threat-detector.js  # 10-family injection/attack detector
│   │   └── logger/
│   │       └── security-log.js     # Structured security event log (5 levels)
│   ├── tools/                      # Tool definition JSON files
│   ├── agents/                     # Agent definition JSON files
│   ├── credentials/                # .env and JSON secrets (gitignored)
│   ├── logs/                       # Security log + call log (gitignored)
│   └── security-tests/             # Attack simulation suite + benchmark
│
├── snapshots/                      # Manager server state snapshots (gitignored)
└── examples/                       # Example tool/agent JSON files

git clone https://github.com/YOUR_USERNAME/mcp-tool-manager.git
cd mcp-tool-manager

# Root (Manager Server + CLI + SDK)
npm install

# Dashboard
cd src/dashboard && npm install && cd ../..

# MCP Server
cd mcp-server-project && npm install && cd ..

# Manager Server
cp .env.example .env
# Edit .env with your JWT_SECRET, ENCRYPTION_KEY, etc.

# MCP Server
cp mcp-server-project/credentials/.env.example mcp-server-project/credentials/.env
# Edit credentials/.env with your agent keys and tool API keys

# Terminal 1 — Manager Server (port 5000)
npm run dev:server

# Terminal 2 — React Dashboard (port 3000)
npm run dev:dashboard

# Terminal 3 — MCP Server (port 5001 by default)
cd mcp-server-project && npm start

Email:    admin@mcp-tool-manager.dev
Password: admin123

# Core
NODE_ENV=development
MCP_SERVER_PORT=5000
MCP_SERVER_HOST=localhost
LOG_LEVEL=info

# Auth
JWT_SECRET=your-super-secret-key-min-32-chars
JWT_EXPIRY=24h
ENCRYPTION_KEY=your-encryption-key-exactly-32-ch

# Context Window
MCP_MAX_RESPONSE_BYTES=65536        # 64 KB default response budget
MCP_MAX_PAGE_SIZE=100               # Max items per paginated endpoint

# Scalability
MCP_MAX_CONNECTIONS=500             # TCP connection limit
SNAPSHOT_DIR=./snapshots            # State persistence directory
SNAPSHOT_INTERVAL_SECS=60           # Save state every 60 seconds
SNAPSHOT_RESTORE=true               # Restore state on startup

# Cache TTLs (seconds)
CACHE_TTL_TOOL_LIST=30
CACHE_TTL_TOOL_ITEM=60
CACHE_TTL_AGENT_LIST=30
CACHE_TTL_STATS=10
CACHE_TTL_ACTIVITY=300

# Future (not yet wired — provide connection string to enable)
DATABASE_URL=postgresql://user:password@localhost:5432/mcp_tools
REDIS_URL=redis://localhost:6379

# Agent API Keys (convention: AGENT_<AGENTID_UPPERCASE>_KEY)
AGENT_MY_AGENT_KEY=your-agent-secret-key

# Tool credentials (referenced by credential_ref in tool JSON)
OPENAI_API_KEY=sk-...
WEATHER_API_KEY=...
SLACK_BOT_TOKEN=xoxb-...

# Admin
ADMIN_KEY=your-admin-key-for-metrics-endpoint

# Server
MCP_PORT=5001
MCP_MAX_CONNECTIONS=200
MCP_MAX_RESPONSE_BYTES=32768        # 32 KB default per tool response

{
  "name": "my_tool",
  "description": "Human-readable description for the LLM",
  "endpoint_url": "https://api.example.com/endpoint",
  "method": "POST",
  "credential_ref": "MY_API_KEY",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" }
    },
    "required": ["query"]
  },
  "cache_ttl_seconds": 60,
  "max_response_bytes": 8192,
  "retry_max": 3,
  "timeout_ms": 10000,
  "circuit_failure_threshold": 5,
  "circuit_open_window_ms": 30000
}

{
  "agent_id": "my-agent",
  "allowed_tools": ["weather_lookup", "send_email"],
  "expires_at": "2027-01-01T00:00:00Z",
  "disabled": false
}

Request
  │
  ├── X-Trace-ID attachment (Layer 0)
  ├── Helmet strict CSP (Layer 1)
  ├── Global rate limit 300/min (Layer 2a)
  ├── Auth rate limit 15/min on /api/auth (Layer 2b)
  ├── Body size limit 2 MB (Layer 3)
  ├── Context window budget (Layer 4)
  ├── Pagination guard max 100 items (Layer 5)
  ├── JWT / API key verification (per-route)
  └── RBAC role check (per-route)

Request
  │
  ├── X-Trace-ID attachment (Layer 0)
  ├── Strict Helmet CSP (Layer 1)
  ├── IP block list check (Layer 2)
  ├── Body size guard (Layer 3)
  ├── Context window budget (Layer 4)
  ├── HTTP method whitelist (Layer 5)
  ├── Scanner user-agent block (Layer 6)
  ├── Global rate limit + speed slow-down (Layer 7)
  ├── 10-family threat detection (Layer 8)
  ├── Agent API key auth + expiry + disabled check (per-route)
  ├── Tool scope enforcement (per-route)
  ├── Circuit breaker check (per-tool)
  ├── Response cache lookup (per-tool)
  └── Retry + context limit on upstream call (per-tool)

Client → [generates or passes X-Trace-ID]
  → Manager/MCP Server [attaches to req.traceId, echoes in X-Trace-ID response header]
    → Security log entries [include traceId]
      → Call log entries [include traceId]
        → Upstream API call [X-Trace-ID forwarded in headers]
          → Response [traceId in JSON body]