MCP智能编排网关

1. Create Spells (Terminal)      →  2. Configure Grimoire (mcp.json)  →  3. Use in AI Agent
   npx mcp-grimoire create           Add to Claude/Copilot config          Ask questions naturally
   - Interactive wizard              - Grimoire runs as MCP gateway        - Servers spawn on-demand
   - Auto-probes server              - Debug with GRIMOIRE_DEBUG           - Auto-cleanup after 5 turns idle

npx @crack-break-make/mcp-grimoire@latest create

{
  "mcpServers": {
    "grimoire": {
      "command": "npx",
      "args": ["-y", "@crack-break-make/mcp-grimoire"]
    }
  }
}

{
  "mcpServers": {
    "grimoire": {
      "command": "npx",
      "args": ["-y", "@crack-break-make/mcp-grimoire"]
    }
  }
}

# List installed spells
npx @crack-break-make/mcp-grimoire@latest list

# Validate a spell configuration
npx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml

# Show help
npx @crack-break-make/mcp-grimoire@latest --help

Show me all users from the database

User Query → Claude analyzes intent → resolve_intent(query) →
Grimoire matches keywords/semantics → Spawns relevant MCP server →
Injects steering → tools/list_changed → Claude sees tools + guidance →
Executes with best practices → After 5 turns idle → Kill server

┌──────────────────────────────────────┐
│      Claude Desktop / Copilot        │
│  Maintains conversation state        │
└──────────────┬───────────────────────┘
               │ stdio (MCP Protocol)
               │
┌──────────────▼───────────────────────┐
│      GRIMOIRE GATEWAY SERVER         │
│  - Intent Resolution (hybrid)        │
│  - Process Lifecycle Management      │
│  - Tool Routing                      │
│  - Steering Injection                │
│  - Authentication Handling           │
└──────┬──────────────┬────────────────┘
       │ stdio/http   │ sse/http
       │ + auth       │ + auth
┌──────▼─────┐  ┌────▼──────┐
│  Postgres  │  │  Stripe   │  ... (spawned on-demand)
│ MCP Server │  │ MCP Server│       with auth headers
└────────────┘  └───────────┘

# Run without installation (recommended)
npx @crack-break-make/mcp-grimoire create

# OR install globally first, then use short command
npm install -g @crack-break-make/mcp-grimoire
grimoire create

name: postgres
version: 1.0.0
description: PostgreSQL database operations

server:
  transport: stdio
  command: npx
  args:
    - '-y'
    - '@modelcontextprotocol/server-postgres'
  env:
    DATABASE_URL: postgresql://user:pass@localhost/db

keywords:
  - database
  - sql
  - query
  - postgres
  - tables
  - users

steering: |
  # Database Schema
  Tables:
    - users (id uuid, email string, created_at timestamp)
    - orders (id uuid, user_id uuid, total decimal)

  # Security Rules
  ALWAYS use parameterized queries:
    ✓ query_database('SELECT * FROM users WHERE id = $1', [id])
    ✗ 'SELECT * FROM users WHERE id = ' + id  (SQL INJECTION!)

  # Performance Tips
  - Use LIMIT to avoid scanning millions of rows
  - created_at is indexed, use for date filtering

name: weather-api
version: 1.0.0
description: Weather forecast and current conditions

server:
  transport: http
  url: http://localhost:8000/mcp
  auth:
    type: bearer
    token: ${WEATHER_API_KEY} # From environment variable

keywords:
  - weather
  - forecast
  - temperature
  - conditions
  - climate

steering: |
  # API Usage
  - Rate limit: 1000 calls/day
  - Forecast available: 7 days ahead
  - Historical data: Not available

  # Best Practices
  - Cache forecast results (updated hourly)
  - Use city name or coordinates
  - Check units: imperial (°F) or metric (°C)

name: github-api
version: 1.0.0
description: GitHub repository and issue management

server:
  transport: sse
  url: http://localhost:8001/sse
  headers:
    X-GitHub-Token: ${GITHUB_PERSONAL_ACCESS_TOKEN}
    Accept: application/vnd.github.v3+json

keywords:
  - github
  - repository
  - repo
  - issues
  - pull
  - requests
  - commits

steering: |
  # GitHub API Guidelines
  - Use full repository names: owner/repo
  - Rate limit: 5000 requests/hour (authenticated)
  - Always check permissions before write operations

  # Security Best Practices
  - Never hardcode tokens (use environment variables)
  - Use fine-grained tokens when possible
  - Minimum required scopes: repo, read:user

server:
  env:
    # Database connections
    DATABASE_URL: ${DATABASE_URL}
    POSTGRES_PASSWORD: ${DB_PASSWORD}

    # API keys
    GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PAT}
    WEATHER_API_KEY: ${WEATHER_KEY}
    STRIPE_SECRET_KEY: ${STRIPE_SECRET}

    # OAuth credentials
    OAUTH_CLIENT_ID: ${ENTERPRISE_CLIENT_ID}
    OAUTH_CLIENT_SECRET: ${ENTERPRISE_SECRET}

# (user.home)/.grimoire/.env
GITHUB_PAT=ghp_your_token_here
WEATHER_KEY=your_weather_api_key
DATABASE_URL=postgresql://user:pass@localhost/db
DB_PASSWORD=your_secure_password
STRIPE_SECRET=sk_test_your_stripe_key
ENTERPRISE_CLIENT_ID=your_oauth_client_id
ENTERPRISE_SECRET=your_oauth_client_secret

server:
  transport: stdio
  command: npx
  args:
    - '-y'
    - '@modelcontextprotocol/server-postgres'

server:
  transport: sse
  url: https://your-sse-url/sse

server:
  transport: http
  url: https://your-http-url/mcp

server:
  transport: stdio
  command: npx
  args: ['-y', '@modelcontextprotocol/server-filesystem']
  # No auth configuration needed

server:
  transport: http
  url: http://localhost:8000/mcp
  auth:
    type: bearer
    token: ${MY_API_KEY} # Environment variable expansion

server:
  transport: http
  url: http://localhost:8001/mcp
  auth:
    type: basic
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}

server:
  transport: sse
  url: http://localhost:8002/sse
  headers:
    X-GitHub-Token: ${GITHUB_TOKEN}
    X-Brave-Key: ${BRAVE_API_KEY}
    X-Custom-Auth: ${CUSTOM_SECRET}

server:
  transport: http
  url: http://localhost:8003/mcp
  auth:
    type: client_credentials
    clientId: ${OAUTH_CLIENT_ID}
    clientSecret: ${OAUTH_CLIENT_SECRET}
    tokenUrl: https://oauth.example.com/token
    scope: read:data write:data # Optional

server:
  transport: http
  url: http://localhost:8004/mcp
  auth:
    type: private_key_jwt
    clientId: ${OAUTH_CLIENT_ID}
    privateKey: ${PRIVATE_KEY_PEM} # PEM format
    tokenUrl: https://oauth.example.com/token
    algorithm: RS256 # Optional: RS256 (default), RS384, RS512, ES256, ES384, ES512

server:
  transport: http
  url: http://localhost:8005/mcp
  auth:
    type: static_private_key_jwt
    clientId: ${OAUTH_CLIENT_ID}
    privateKey: ${PRIVATE_KEY_PEM}
    tokenUrl: https://oauth.example.com/token
    staticClaims:
      sub: service-account@example.com
      aud: https://api.example.com

server:
  transport: http
  url: http://localhost:8006/mcp
  auth:
    type: authorization_code
    clientId: ${OAUTH_CLIENT_ID}
    clientSecret: ${OAUTH_CLIENT_SECRET}
    authorizationUrl: https://oauth.example.com/authorize
    tokenUrl: https://oauth.example.com/token
    redirectUri: http://localhost:3000/callback

User: "query my postgres database"
→ resolve_intent matches "postgres" with 0.94 confidence
→ Immediate spawn + return tools
→ Time: 200-300ms

User: "check my database"
→ resolve_intent returns alternatives: [postgres, mysql, mongodb]
→ Claude (or user) calls: activate_spell({ name: "postgres" })
→ Spawn specified spell
→ Time: 200-300ms

→ Just update usage tracking
→ Time: ~5ms (no spawn overhead)

If (currentTurn - lastUsedTurn) >= 5:
  → Kill process
  → Unregister tools
  → Send tools/list_changed notification

# Interactive mode (guided) - RECOMMENDED
npx @crack-break-make/mcp-grimoire@latest create

# With server validation (auto-generates steering)
npx @crack-break-make/mcp-grimoire@latest create --probe

# Non-interactive mode
npx @crack-break-make/mcp-grimoire@latest create \
  -n postgres \
  -t stdio \
  --command npx \
  --args "-y" "@modelcontextprotocol/server-postgres"

# With environment variables (for authenticated servers)
npx @crack-break-make/mcp-grimoire@latest create \
  -n github \
  -t stdio \
  --command npx \
  --args "-y" "@modelcontextprotocol/server-github" \
  --env "GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}"

npm install -g @crack-break-make/mcp-grimoire@latest

# Now use short form:
grimoire create
grimoire list

# Simple list
npx @crack-break-make/mcp-grimoire@latest list

# Verbose output with details
npx @crack-break-make/mcp-grimoire@latest list -v

📚 Spells in ~/.grimoire

  🔮 postgres                    [stdio ] (8 keywords)
  🔮 stripe                      [stdio ] (12 keywords)
  🔮 github-api                  [stdio ] (15 keywords)

✓ Total: 3 spells

npx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml

{
  "servers": {
    "grimoire": {
      "command": "npx",
      "args": ["-y", "@crack-break-make/mcp-grimoire"]
    }
  }
}

All 50 servers spawned at startup:
- postgres tools (8 tools × 200 tokens) = 1,600 tokens
- stripe tools (12 tools × 200 tokens) = 2,400 tokens
- github tools (15 tools × 200 tokens) = 3,000 tokens
- ... 47 more servers
= ~40,000 tokens per conversation

High confidence (70%):   1,000 tokens (selected tools only)
Medium confidence (20%): 1,500 tokens (3 alternatives + tools)
Low confidence (8%):     2,000 tokens (5 weak matches + tools)
No match (2%):             300 tokens (error + available spells)

Average = 0.70×1000 + 0.20×1500 + 0.08×2000 + 0.02×300
        = 700 + 300 + 160 + 6
        = 1,166 tokens

# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/mcp-grimoire.git
cd mcp-grimoire

# Install dependencies
pnpm install

git checkout -b feature/my-awesome-feature

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Format
type(scope): short description

# Examples
feat(intent): add semantic search with embeddings
fix(lifecycle): prevent orphaned child processes
docs(readme): add contributing section
test(gateway): add multi-tier resolution tests

git push origin feature/my-awesome-feature

# Development server (hot reload)
pnpm dev

# Build TypeScript
pnpm build

# Linting
pnpm lint          # Check for issues
pnpm lint:fix      # Auto-fix issues

# Formatting
pnpm format        # Format all files with Prettier

# Type checking
pnpm type-check    # Check TypeScript types

mcp-grimoire/
├── src/
│   ├── core/                    # Domain models (types, configs)
│   ├── application/             # Business logic (intent, lifecycle)
│   ├── infrastructure/          # External systems (file, embeddings)
│   ├── presentation/            # Gateway server, tool routing
│   ├── cli/                     # CLI commands, templates
│   └── utils/                   # Shared utilities
├── tests/
│   └── fixtures/                # Test spell configurations
├── docs/
│   ├── adr/                     # Architecture Decision Records
│   └── architecture.md          # System architecture

# Use the adr-generator skill
/adr-generator --title "Use Hybrid Intent Resolution" --status proposed

# Requires test servers to be available
pnpm test:integration

# Run specific integration test
pnpm test src/presentation/__tests__/gateway-real-workflow.integration.test.ts

Please call the tools/list API to refresh available tools, then use the resolve_intent tool to search for [your query].