{
  "name": "chatctx",
  "version": "0.1.0",
  "description": "Reviewed engineering guidance for coding agents, served over the Model Context Protocol. Read-only retrieval with source provenance and explicit no-match. No generative model runs in the retrieval path.",
  "site": "https://chatctx.pages.dev/",
  "transport": {
    "type": "streamable-http",
    "stateless": true,
    "url": "https://chatctx-mcp.brackket.workers.dev/mcp",
    "methods": {
      "POST": "JSON-RPC requests and notifications",
      "GET": "keep-alive SSE stream for clients that probe before posting"
    },
    "request_headers": {
      "Content-Type": "application/json",
      "Accept": "application/json, text/event-stream"
    },
    "response_framing": "Server-Sent Events. Parse the data: line of each event: message block.",
    "handshake": ["initialize", "notifications/initialized", "tools/list", "tools/call"]
  },
  "server": {
    "name": "chatctx-knowledge",
    "capabilities": { "tools": true },
    "tool_annotations": {
      "search_knowledge": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false },
      "get_guidance": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false },
      "submit_feedback": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false }
    }
  },
  "auth": {
    "scheme": "bearer",
    "header": "Authorization",
    "format": "Bearer kb_live_<prefix>_<secret>",
    "storage": "HMAC-SHA256 hash with a server-side pepper; plaintext is shown once at creation",
    "revocable": true,
    "guest_access": {
      "enabled": true,
      "scope": "production",
      "quota": "250 tool calls per client IP per UTC day",
      "invalid_token_behavior": "401, never falls back to guest access"
    }
  },
  "tools": [
    {
      "name": "search_knowledge",
      "title": "Search engineering knowledge",
      "description": "Find concise, reviewed engineering guidance for an implementation decision. Returns recommendations with applicability, caveats, verification checks, and source links. Similarity and rank are retrieval signals, not proof that guidance applies.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2000,
            "description": "The implementation decision or question, phrased naturally."
          },
          "technologies": {
            "type": "array",
            "maxItems": 10,
            "items": { "type": "string", "minLength": 1, "maxLength": 80 },
            "default": [],
            "description": "Technology filters such as React, Next.js, PostgreSQL."
          },
          "versions": {
            "type": "object",
            "maxProperties": 20,
            "additionalProperties": { "type": "string" },
            "default": {},
            "description": "Requested versions keyed by technology."
          },
          "topic": {
            "oneOf": [
              { "type": "string", "enum": ["architecture", "implementation", "security", "accessibility", "ux", "reliability", "testing", "performance", "data", "observability", "tooling"] },
              {
                "type": "array",
                "maxItems": 3,
                "items": { "type": "string", "enum": ["architecture", "implementation", "security", "accessibility", "ux", "reliability", "testing", "performance", "data", "observability", "tooling"] }
              }
            ]
          },
          "task_type": {
            "type": "string",
            "enum": ["build", "architecture", "debug", "security", "accessibility", "performance", "testing", "review", "other"]
          },
          "max_results": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 },
          "detail": { "type": "string", "enum": ["brief", "standard"], "default": "brief" },
          "token_budget": { "type": "integer", "minimum": 200, "maximum": 5000, "default": 2500 }
        }
      },
      "returns": {
        "query_summary": "string",
        "results": "array of guidance records",
        "retrieval": "object describing mode, degradation, embedding provider, cache state",
        "suggestions": "array of strings, present on no_match"
      }
    },
    {
      "name": "get_guidance",
      "title": "Get full guidance records",
      "description": "Fetch full, reviewed guidance for one or more record ids or slugs returned by search_knowledge. Returns applicability, exceptions, pitfalls, verification checks, and provenance.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ids"],
        "properties": {
          "ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": { "type": "string", "minLength": 1, "maxLength": 120 },
            "description": "Record slugs or ids returned by search_knowledge."
          },
          "detail": { "type": "string", "enum": ["brief", "full"], "default": "full" }
        }
      },
      "returns": {
        "results": "array of full guidance records",
        "missing": "array of identifiers that were unknown, deprecated, or not public"
      }
    },
    {
      "name": "submit_feedback",
      "title": "Submit anonymous guidance feedback",
      "description": "Submit anonymous feedback about guidance retrieved with search_knowledge or get_guidance. Do not include source code, secrets, credentials, customer data, or personal information.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category"],
        "properties": {
          "category": {
            "type": "string",
            "enum": ["helpful", "not_helpful", "incorrect", "outdated", "missing", "other"]
          },
          "record": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional approved slug or id." },
          "source": { "type": "string", "enum": ["search_knowledge", "get_guidance", "other"], "default": "other" },
          "comment": { "type": "string", "minLength": 1, "maxLength": 1000 }
        }
      },
      "returns": {
        "accepted": "boolean",
        "id": "uuid of the stored feedback row",
        "message": "string"
      }
    }
  ],
  "response_schema": {
    "result": {
      "id": "string",
      "slug": "string",
      "title": "string",
      "topic": "one of the topic enum values",
      "summary": "string (optional)",
      "recommendation": "string",
      "rationale": "string (optional)",
      "applies_to": "array of {kind, name, version_constraint?}",
      "conditions": "array of strings (optional)",
      "exceptions": "array of strings (optional)",
      "pitfalls": "array of strings (optional)",
      "verification_checks": "array of strings (optional)",
      "confidence": "\"high\" | \"medium\" | \"low\" (optional)",
      "updated_at": "ISO-8601 string",
      "sources": "array of {title, url, publisher?, evidence_excerpt?, relation?}"
    },
    "retrieval": {
      "mode": ["hybrid", "keyword_fallback", "no_match"],
      "degraded": "boolean",
      "degraded_reason": "string (optional)",
      "embedding_provider": "string (optional)",
      "embedding_cache": ["hit", "miss"],
      "total_candidates": "integer (optional)",
      "technology_filter_fallback": "boolean (optional)",
      "truncated": "boolean (optional)"
    }
  },
  "limits": {
    "query_characters": { "min": 2, "max": 2000 },
    "technologies": { "max_items": 10, "item_max_characters": 80 },
    "versions": { "max_properties": 20 },
    "topics": { "max_items": 3 },
    "max_results": { "min": 1, "max": 10, "default": 5 },
    "token_budget": { "min": 200, "max": 5000, "default": 2500 },
    "get_guidance_ids": { "min": 1, "max": 10 },
    "feedback_comment_characters": { "max": 1000 },
    "guest_daily_tool_calls": 250
  },
  "http_errors": [
    { "status": 401, "meaning": "missing, malformed, or revoked API key", "action": "fix the bearer token or use guest access" },
    { "status": 403, "meaning": "host or origin not allowed", "action": "use the documented endpoint host" },
    { "status": 406, "meaning": "missing SSE Accept value", "action": "send Accept: application/json, text/event-stream" },
    { "status": 429, "meaning": "daily quota exhausted", "action": "back off until Retry-After; request a higher quota" }
  ],
  "tool_error_shape": {
    "isError": true,
    "content": "[{\"type\":\"text\",\"text\":\"{\\\"error\\\":{\\\"code\\\":\\\"...\\\",\\\"message\\\":\\\"...\\\"}}\"}]"
  },
  "guarantees": [
    "Only reviewed, approved records are served.",
    "Every result carries sources, evidence relation, and record timestamps.",
    "Embeddings only select candidates; guidance text is human-authored.",
    "Weak matches return no_match with suggestions instead of invented guidance."
  ],
  "privacy": {
    "raw_queries_logged": false,
    "retrieval_analytics": "salted hash plus topic, technology filters, mode, result count, degraded state",
    "query_embedding_cache": "keyed by hash, model, and dimensions; raw text is never stored",
    "feedback_identifiers": "none stored",
    "guest_quota_ip": "HMAC-SHA256 hash only"
  },
  "docs": {
    "index": "https://chatctx.pages.dev/llms.txt",
    "full": "https://chatctx.pages.dev/llms-full.txt",
    "markdown": "https://chatctx.pages.dev/docs.md",
    "html": "https://chatctx.pages.dev/docs",
    "agent_instructions": "https://chatctx.pages.dev/agent-instructions.md",
    "client_config": "https://chatctx.pages.dev/mcp.json"
  }
}