# MCP is JSON-RPC 2.0. The two key methods are:
#   - tools/list   (discover tools)
#   - tools/call   (invoke a tool)

──────────────────────────────────────────────────────────────────────────────
1) DISCOVER TOOLS: tools/list
──────────────────────────────────────────────────────────────────────────────

CLIENT → MCP SERVER  (JSON-RPC request)
{
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "tools/list",
  "params": {}
}

MCP SERVER → CLIENT  (JSON-RPC response)
{
  "jsonrpc": "2.0",
  "id": "req_1",
  "result": {
    "tools": [
      {
        "name": "search_issues",
        "description": "Search issues in TrackerX",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "limit": { "type": "integer", "default": 10 }
          },
          "required": ["query"]
        }
      },
      {
        "name": "get_issue",
        "description": "Fetch a single issue by id",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": { "type": "string" }
          },
          "required": ["id"]
        }
      }
    ]
  }
}

# (Client then maps MCP inputSchema → model input_schema and includes these tools
#  in the LLM request as normal tools.)

──────────────────────────────────────────────────────────────────────────────
2) CALL A TOOL: tools/call
──────────────────────────────────────────────────────────────────────────────

CLIENT → MCP SERVER  (JSON-RPC request)
{
  "jsonrpc": "2.0",
  "id": "req_2",
  "method": "tools/call",
  "params": {
    "name": "search_issues",
    "arguments": {
      "query": "auth bug",
      "limit": 5
    }
  }
}

MCP SERVER → CLIENT  (JSON-RPC response)
{
  "jsonrpc": "2.0",
  "id": "req_2",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 2 issues:\n- AUTH-123: Login fails on Safari\n- AUTH-987: Token refresh loop"
      }
    ],
    "isError": false
  }
}

# (Client then wraps that content into the LLM's tool_result shape and sends back
#  as part of the conversation history.)

──────────────────────────────────────────────────────────────────────────────
3) (OPTIONAL) ERROR EXAMPLE
──────────────────────────────────────────────────────────────────────────────

CLIENT → MCP SERVER
{
  "jsonrpc": "2.0",
  "id": "req_3",
  "method": "tools/call",
  "params": {
    "name": "get_issue",
    "arguments": { "id": "" }
  }
}

MCP SERVER → CLIENT
{
  "jsonrpc": "2.0",
  "id": "req_3",
  "result": {
    "content": [
      { "type": "text", "text": "id is required" }
    ],
    "isError": true
  }
}

# pseudocode: MCP stdio server (JSON-RPC 2.0)
# - reads one JSON object per line from stdin
# - writes one JSON object per line to stdout
# - exposes tools/list and tools/call

import sys
import json
import os

# ---------------------------
# helpers
# ---------------------------

def read_json_line():
    line = sys.stdin.readline()
    if not line:
        return None
    return json.loads(line)

def write_json(obj):
    sys.stdout.write(json.dumps(obj) + "\n")
    sys.stdout.flush()

def reply_ok(req_id, result_obj):
    write_json({
        "jsonrpc": "2.0",
        "id": req_id,
        "result": result_obj
    })

def reply_err(req_id, code, message, data=None):
    err = {"code": code, "message": message}
    if data is not None:
        err["data"] = data
    write_json({
        "jsonrpc": "2.0",
        "id": req_id,
        "error": err
    })

# ---------------------------
# server state / secrets
# ---------------------------

DB_URL   = os.getenv("DB_URL")            # server-only secret
API_KEY  = os.getenv("VENDOR_API_KEY")    # server-only secret

db = db_connect(DB_URL)                   # pseudocode
http = http_client()                      # pseudocode

TOOLS = [
    {
        "name": "get_customer_by_id",
        "description": "Fetch a customer record by internal id",
        "inputSchema": {
            "type": "object",
            "properties": {"customer_id": {"type": "integer"}},
            "required": ["customer_id"]
        }
    },
    {
        "name": "vendor_search",
        "description": "Search vendor tickets by query",
        "inputSchema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "limit": {"type": "integer", "default": 5}
            },
            "required": ["query"]
        }
    }
]

# ---------------------------
# tool implementations
# ---------------------------

def tool_get_customer_by_id(args):
    cid = args["customer_id"]
    row = db.query_one(
        "SELECT id, name, email FROM customers WHERE id = ?",
        [cid]
    )
    return {"content": [{"type": "text", "text": json.dumps(row)}], "isError": False}

def tool_vendor_search(args):
    q = args["query"]
    limit = args.get("limit", 5)

    resp = http.get(
        "https://api.vendor.com/tickets/search",
        params={"q": q, "limit": limit},
        headers={"Authorization": "Bearer " + API_KEY, "Accept": "application/json"},
        timeout_ms=8000
    )

    if resp.status != 200:
        return {"content": [{"type": "text", "text": resp.body_text}], "isError": True}

    return {"content": [{"type": "text", "text": json.dumps(resp.json())}], "isError": False}

TOOL_HANDLERS = {
    "get_customer_by_id": tool_get_customer_by_id,
    "vendor_search": tool_vendor_search,
}

# ---------------------------
# JSON-RPC loop
# ---------------------------

def main():
    while True:
        msg = read_json_line()
        if msg is None:
            break  # stdin closed

        req_id = msg.get("id")
        method = msg.get("method")

        # notifications have no id; ignore or handle separately
        if req_id is None:
            continue

        if method == "tools/list":
            reply_ok(req_id, {"tools": TOOLS})
            continue

        if method == "tools/call":
            params = msg.get("params") or {}
            name = params.get("name")
            args = params.get("arguments") or {}

            handler = TOOL_HANDLERS.get(name)
            if not handler:
                reply_ok(req_id, {"content": [{"type": "text", "text": "Unknown tool"}], "isError": True})
                continue

            try:
                result = handler(args)
                reply_ok(req_id, result)
            except Exception as e:
                # don't leak secrets; return a sanitized error
                reply_ok(req_id, {"content": [{"type": "text", "text": "Tool execution failed"}], "isError": True})
            continue

        reply_err(req_id, -32601, "Method not found")

if __name__ == "__main__":
    main()

# PSEUDOCODE: MCP SERVER (stdio JSON-RPC) that:
  - authenticates to a DATABASE (server holds creds)
  - exposes safe tools (no raw SQL from the model)
  - calls a 3rd-party API using an API key (server holds key)

Notes:
- In MCP, the MODEL never receives your DB password / API key.
- The MCP server runs with secrets (env/config) and returns only results.

──────────────────────────────────────────────────────────────────────────────
A) CUSTOM MCP SERVER WITH DATABASE AUTH
──────────────────────────────────────────────────────────────────────────────

# startup
DB_HOST = env("DB_HOST")
DB_PORT = env("DB_PORT")
DB_NAME = env("DB_NAME")
DB_USER = env("DB_USER")
DB_PASS = env("DB_PASS")

db = db_connect(
  host=DB_HOST, port=DB_PORT, database=DB_NAME,
  user=DB_USER, password=DB_PASS,
  pool_size=10
)

TOOLS = [
  {
    "name": "get_customer_by_id",
    "description": "Fetch a customer record by internal id",
    "inputSchema": {
      "type": "object",
      "properties": {"customer_id": {"type": "integer"}},
      "required": ["customer_id"]
    }
  },
  {
    "name": "search_orders",
    "description": "Search orders by email (exact match) with limit",
    "inputSchema": {
      "type": "object",
      "properties": {
        "email": {"type": "string"},
        "limit": {"type": "integer", "default": 20}
      },
      "required": ["email"]
    }
  }
]

# JSON-RPC loop (stdio)
while msg := read_json_line(stdin):
  if msg.method == "tools/list":
    reply(msg.id, { "tools": TOOLS })

  elif msg.method == "tools/call":
    tool = msg.params.name
    args = msg.params.arguments

    if tool == "get_customer_by_id":
      # IMPORTANT: parameterized query, fixed SQL (no model SQL)
      row = db.query_one(
        "SELECT id, name, email, created_at FROM customers WHERE id = ?",
        [args.customer_id]
      )
      reply(msg.id, {
        "content": [{ "type": "text", "text": json(row) }],
        "isError": false
      })

    elif tool == "search_orders":
      rows = db.query_all(
        "SELECT id, total, status, created_at FROM orders WHERE email = ? ORDER BY created_at DESC LIMIT ?",
        [args.email, args.limit]
      )
      reply(msg.id, {
        "content": [{ "type": "text", "text": json(rows) }],
        "isError": false
      })

    else:
      reply(msg.id, {
        "content": [{ "type": "text", "text": "Unknown tool" }],
        "isError": true
      })

──────────────────────────────────────────────────────────────────────────────
B) MCP SERVER CALLING A 3RD-PARTY SERVICE WITH AN API KEY
──────────────────────────────────────────────────────────────────────────────

API_BASE = "https://api.vendor.com"
API_KEY  = env("VENDOR_API_KEY")          # stored only on server
# or env("VENDOR_API_KEY") could be injected by Claude Code config

TOOLS += [
  {
    "name": "vendor_search",
    "description": "Search Vendor tickets by query",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"},
        "limit": {"type": "integer", "default": 5}
      },
      "required": ["query"]
    }
  }
]

# inside tools/call handler
if tool == "vendor_search":
  q = args.query
  limit = args.limit

  resp = http_get(
    url = API_BASE + "/tickets/search",
    params = { "q": q, "limit": limit },
    headers = {
      "Authorization": "Bearer " + API_KEY,   # or "x-api-key": API_KEY
      "Accept": "application/json"
    },
    timeout_ms = 8000
  )

  if resp.status != 200:
    reply(msg.id, { "content":[{"type":"text","text": resp.body_text}], "isError": true })
  else:
    data = resp.json()
    reply(msg.id, { "content":[{"type":"text","text": json(data)}], "isError": false })

──────────────────────────────────────────────────────────────────────────────
C) HOW SECRETS GET INTO THE SERVER (Claude Code side)
──────────────────────────────────────────────────────────────────────────────

# Local stdio server: pass secrets via env
claude mcp add --transport stdio --env DB_USER=... --env DB_PASS=... --env VENDOR_API_KEY=... myserver -- python mcp_server.py

# Remote HTTP server: pass API key via headers (client → server)
claude mcp add --transport http myremote https://mcp.vendor.com
# and configure headers (conceptually):
headers = { "Authorization": "Bearer <token>" }

# Either way:
# - Claude model sees tool schemas + names
# - Server sees secrets
# - Results returned are data-only (never echo secrets)

---
name: time-off
description: Determine time off / leave eligibility and next steps
---
# Skill: Time Off / Leave

When the user asks about time off, leave, vacation policy, EI, mat leave, etc:

1) Identify jurisdiction and employment type
- Country/province/state
- employee vs contractor
- union / public sector if relevant
- start date / tenure, if relevant

2) Ask only the minimum clarifying questions needed
- If jurisdiction is unknown: ask for it first
- If employer policy vs legal minimum is ambiguous: ask which they mean

3) Separate sources explicitly
- Legal minimums (statutory)
- Employer policy (contract/handbook)
- Practical advice (how people usually handle it)

4) Output format
- Short answer (1–2 sentences)
- Then bullets: "What's legally true", "What's policy-dependent", "What I'd do next"
- If high uncertainty: say exactly what detail is missing

5) Tool use guidance
- If there's a company handbook file locally, read it first
- Otherwise, use web search for statutory rules for the stated jurisdiction
- Do not speculate when dates/thresholds matter; ask or search

1. UserPromptSubmit — force skill activation

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-router.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')

if echo "$PROMPT" | grep -qiE '(test|spec|coverage)'; then
  SKILL="testing-patterns"
elif echo "$PROMPT" | grep -qiE '(api|endpoint|route)'; then
  SKILL="backend-guidelines"
else
  exit 0
fi

echo "MANDATORY: Use Skill($SKILL) BEFORE responding. Do NOT skip this step."
exit 0

Notice how echo is used to print text to the terminal, which Claude sees as if someone typed it into the conversation

2. PreToolUse — block dangerous commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' | grep -qiE 'rm -rf|drop table|force push' && echo 'Blocked: dangerous command' >&2 && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

3. SessionStart — inject project context

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Recent changes:\n$(cd \"$CLAUDE_PROJECT_DIR\" && git log --oneline -5 2>/dev/null)\""
          }
        ]
      }
    ]
  }
}

4. Notification — play a sound when Claude needs input

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}