chatctx — complete documentation for language models ==================================================== > chatctx serves concise, owner-reviewed engineering guidance to coding agents over the Model Context Protocol. Read-only retrieval, source provenance, explicit no-match. No generative model runs in the retrieval path. This file is the whole public contract in one place. It is plain text so a model can consume it in a single fetch. Source of truth: https://chatctx.pages.dev/docs.md Endpoint: https://chatctx-mcp.brackket.workers.dev/mcp Site: https://chatctx.pages.dev/ Structured copy: https://chatctx.pages.dev/api.json 1. WHAT THE SERVICE IS ---------------------- chatctx is a hosted knowledge base. An agent describes the implementation decision it is making and receives a small set of approved records. Each record contains: - recommendation: the action to take - rationale: why it holds - applies_to: languages, frameworks, tools, and version constraints - conditions: when the guidance applies - exceptions: when not to apply it - pitfalls: failure modes to avoid - verification_checks: how to confirm the change worked - sources: title, URL, publisher, evidence excerpt, relation - confidence, updated_at, and, for full records, status, content_version, approved_at Records are reviewed and approved by a human owner before publication. Quality gates check evidence, source authority, freshness, license, version scope, duplicates, and conflicts. Unreviewed candidates never reach the public endpoint. Embeddings are used only to find candidate records. The guidance text is human-authored. No generative model writes answers at query time. Similarity and rank are retrieval signals, not proof that guidance applies. Read `applies_to`, `conditions`, and `exceptions` before acting. 2. CONNECTION ------------- Endpoint: https://chatctx-mcp.brackket.workers.dev/mcp Transport: MCP Streamable HTTP, stateless Methods: POST for JSON-RPC requests and notifications; GET opens a keep-alive SSE stream Server name reported in initialize: chatctx-knowledge Capabilities: tools only (no prompts, resources, sampling, or elicitation) No Mcp-Session-Id is issued or required. Every POST is independent and must carry its own credentials. Required request headers: Content-Type: application/json Accept: application/json, text/event-stream Responses are SSE-framed. Parse the `data:` line: event: message data: {"jsonrpc":"2.0","id":1,"result":{...}} A GET stream may contain `: connected` and `: keepalive` comment lines. Ignore comments. Handshake: 1. POST initialize 2. POST notifications/initialized 3. POST tools/list or tools/call 3. AUTHENTICATION ----------------- Send: Authorization: Bearer kb_live__ Keys are stored server-side as HMAC-SHA256 hashes with a pepper. The plaintext is shown once at creation. Owners can revoke a key or set a daily tool-call quota. Anonymous guest access is enabled on the production endpoint: 250 tool calls per client IP per UTC day. Guest responses include X-Guest-Quota-Limit and X-Guest-Quota-Remaining. An invalid or revoked bearer token returns 401. It never falls through to guest access. 4. TOOLS -------- 4.1 search_knowledge -------------------- Purpose: hybrid retrieval over approved guidance. PostgreSQL full-text search and pgvector cosine search run, rankings are fused, applicability bonuses are applied for requested technologies and versions, and results are shaped to the token budget. Arguments (JSON object, additionalProperties: false): query string required, 2-2000 characters technologies array max 10 items, each 1-80 characters, default [] versions object max 20 properties, string values, default {} topic string or array of strings, max 3 when an array, optional task_type string, optional max_results integer 1-10, default 5 detail string "brief" or "standard", default "brief" token_budget integer 200-5000, default 2500 topic values: architecture, implementation, security, accessibility, ux, reliability, testing, performance, data, observability, tooling task_type values: build, architecture, debug, security, accessibility, performance, testing, review, other Example: {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{ "name":"search_knowledge", "arguments":{ "query":"React list rows keep the wrong state after reordering", "technologies":["React"], "topic":"implementation", "max_results":3 }}} Tool annotations: readOnlyHint true, destructiveHint false, openWorldHint false. 4.2 get_guidance ---------------- Purpose: fetch full records for identifiers returned by search_knowledge. Use it when the brief result is relevant and you need exceptions, pitfalls, verification checks, version constraints, or examples before acting. Arguments (additionalProperties: false): ids array required, 1-10 slugs or ids, each 1-120 characters detail string "brief" or "full", default "full" Example: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{ "name":"get_guidance", "arguments":{"ids":["use-stable-keys-for-dynamic-react-lists"],"detail":"full"}}} Identifiers that are unknown, deprecated, or not publicly approved are returned in `missing` rather than failing the call. Tool annotations: readOnlyHint true, destructiveHint false, openWorldHint false. 4.3 submit_feedback ------------------- Purpose: anonymous signal about retrieval quality. Owner-reviewed. It is never used automatically as ranking input. Arguments (additionalProperties: false): category string required: helpful | not_helpful | incorrect | outdated | missing | other record string optional approved slug or id, 1-120 characters source string search_knowledge | get_guidance | other, default other comment string optional, 1-1000 characters Example: {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{ "name":"submit_feedback", "arguments":{"category":"outdated","record":"use-stable-keys-for-dynamic-react-lists", "source":"search_knowledge","comment":"The linked React docs moved."}}} Never include source code, secrets, credentials, customer data, or personal information in the comment. Feedback rows store no API key, IP address, user agent, or client identifier. Tool annotations: readOnlyHint false, destructiveHint false, openWorldHint false. 5. RESPONSE SHAPE ----------------- search_knowledge returns: { "query_summary": "implementation · React", "results": [ { "id": "uuid", "slug": "kebab-case-identifier", "title": "string", "topic": "implementation", "summary": "string (optional)", "recommendation": "string", "rationale": "string (optional)", "applies_to": [{"kind":"framework","name":"React","version_constraint":">=16.0"}], "conditions": ["string"], "exceptions": ["string"], "pitfalls": ["string"], "verification_checks": ["string"], "confidence": "high | medium | low", "updated_at": "ISO-8601", "sources": [ { "title": "string", "url": "https://...", "publisher": "string (optional)", "evidence_excerpt": "string (optional)", "relation": "supports | ..." } ] } ], "retrieval": { "mode": "hybrid | keyword_fallback | no_match", "degraded": false, "degraded_reason": "string (optional)", "embedding_provider": "string (optional)", "embedding_cache": "hit | miss (optional)", "total_candidates": 20, "technology_filter_fallback": false, "truncated": false }, "suggestions": ["string"] } get_guidance returns: { "results": [ { ...same fields as search results..., "status": "approved", "content_version": 3, "approved_at": "ISO-8601", "version_constraints": {"React": ">=18"}, "examples": "string" } ], "missing": ["identifier"] } submit_feedback returns: {"accepted": true, "id": "uuid", "message": "Anonymous feedback recorded for owner review."} 6. RETRIEVAL MODES ------------------ hybrid Text and vector results were fused. Normal operation. keyword_fallback No query embedding was available, so only full-text search ran. `degraded` is true and `degraded_reason` explains why. Recall is lower; the returned guidance text is unchanged. no_match Nothing cleared the relevance threshold. `results` is empty and `suggestions` explains how to broaden the query. This means "not in the knowledge base", not "error". Do not invent guidance that the service did not return. degraded: true Part of the retrieval path failed. Treat recall as reduced. technology_filter_fallback: true Technology filters were too narrow, so the server retried without them. truncated: true The token budget cut the result list. 7. ERRORS AND LIMITS -------------------- HTTP status: 401 Missing, malformed, or revoked API key. Fix the bearer token or use guest access. 403 Host or origin not allowed. Use the documented endpoint host. 406 Missing SSE Accept value. Send Accept: application/json, text/event-stream. 429 Daily quota exhausted. Back off until Retry-After; request a higher quota. Tool-level errors return a successful JSON-RPC response whose result has isError: true and: {"error":{"code":"validation_error","message":"...","details":{...}}} Codes are stable strings. Internal failures never include stack traces or query text. Hard limits: query length 2-2000 characters technologies 10 items, 80 characters each versions 20 keys topics 3 per call max_results 10 per call token_budget 5000 per call get_guidance ids 10 per call feedback comment 1000 characters guest quota 250 tool calls per IP per UTC day (production) 8. PRIVACY ---------- - Raw search queries are not written to structured logs. - Retrieval analytics store a salted hash of the query plus topic, technology filters, mode, result count, and degraded state. - Query embeddings are cached by a hash of the normalized query together with model and dimensions. Raw query text is never stored. - Feedback excludes API key ids, IP addresses, user agents, and client identifiers. - Guest quota accounting stores an HMAC-SHA256 hash of the client IP, never the address. 9. WHEN TO USE chatctx ---------------------- Use it before: - choosing a framework-specific practice - implementing a security control - applying an accessibility pattern - deciding on a testing or reliability strategy - reviewing code against established guidance Do not use it for: - general chit-chat or code generation - secrets, credentials, customer data, or private source code - facts outside the reviewed engineering corpus If a result is unhelpful, incorrect, outdated, or missing, call submit_feedback. That signal reaches the owner and never changes ranking automatically. 10. CLIENT CONFIGURATION ------------------------ { "servers": { "chatctx": { "type": "http", "url": "https://chatctx-mcp.brackket.workers.dev/mcp", "headers": { "Authorization": "Bearer ${input:chatctx-key}" } } } } 11. MACHINE-READABLE FILES -------------------------- /llms.txt text/plain compact index for models /llms-full.txt text/plain this document /docs.md text/markdown full reference /api.json application/json JSON Schemas, limits, errors /agent-instructions.md text/markdown copy-paste agent policy /mcp.json application/json client configuration snippet /sitemap.xml application/xml canonical pages /robots.txt text/plain crawling policy End of document.