{
  "markdown": "# KATA\n\n**Teach repeatable research workflows once, then expose them as deterministic tools for humans and agents.**\n\nKATA combines a real scholarly-data connector, a durable browser workspace, demonstration-derived workflow programs and one canonical semantic engine exposed through HTTPS, remote MCP, browser WebMCP and model-native function schemas.\n\n[**Try KATA**](https://kata-webmcp.vercel.app/) · [Developers](https://kata-webmcp.vercel.app/developers) · [Tools](https://kata-webmcp.vercel.app/tools) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Roadmap](ROADMAP.md)\n\n[![KATA Release Gate](https://github.com/dharan1007/kata/actions/workflows/release-gate.yml/badge.svg)](https://github.com/dharan1007/kata/actions/workflows/release-gate.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## The idea in one minute\n\n```text\nresearch task\n   ↓\nsearch real scholarly data\n   ↓\nsave / prioritize / tag / annotate\n   ↓\ndemonstrate a workflow twice\n   ↓\nKATA anti-unifies the demonstrations\n   ↓\nportable validated workflow program\n   ↓\ninvoke through UI / HTTPS / MCP / WebMCP / model tool schemas\n```\n\nKATA's goal is not to hide nondeterminism behind an \"agent\" label. Connector failures remain explicit. Tool arguments are schema-validated. Automations are preview-bound. Browser cancellation is propagated through fetch/state commits. The same semantic engine powers every surface.\n\n## Try the real product\n\nOpen [kata-webmcp.vercel.app](https://kata-webmcp.vercel.app/) and use the product routes:\n\n- `/research` — search live OpenAlex data and work with normalized results.\n- `/dashboard` — inspect the durable browser workspace.\n- `/automations` — create preview-bound automations.\n- `/teach` — derive reusable programs from demonstrations.\n- `/tools` — inspect the canonical tool surface.\n- `/developers` — integration and protocol guidance.\n- `/activity` — inspect recent workspace activity.\n\nThe production connector is **OpenAlex**. KATA does not replace a failed real connector request with synthetic success data.\n\n## Why KATA exists\n\nAgent workflows often fail in two opposite ways:\n\n1. every new workflow becomes hand-written integration code, or\n2. a model is given broad tools and expected to rediscover the procedure every time.\n\nKATA explores a stricter middle layer: reusable workflow semantics derived from examples, represented as validated programs and invoked through a stable canonical tool registry.\n\n| Problem | KATA's boundary |\n|---|---|\n| Scholarly discovery | Live OpenAlex search with typed upstream failures |\n| Repeated human procedure | Two-demonstration anti-unification into portable programs |\n| Agent integration | Canonical schemas projected into multiple tool protocols |\n| Browser automation | Preview-bound triggers and bounded nested execution |\n| Protocol drift | Explicit MCP compatibility paths rather than silent guessing |\n| Cancellation | Abort propagated through browser requests/state commits |\n| Cross-origin exposure | Default deny; explicit origin configuration required |\n| State | Browser-owned durable workspace; no hidden cloud-workspace claims |\n\n## What is implemented\n\n- Live OpenAlex search with bounded retry, timeout, normalization, optional API-key authentication and rate-limit telemetry.\n- Versioned durable browser workspace.\n- Allowlisted semantic commands for saved work, priority, tags and notes.\n- Preview-bound transactional automations with `AFTER_SEARCH`, `WORKSPACE_OPEN` and `MANUAL` triggers.\n- Nested automation tool calls with a maximum execution depth of four.\n- Two-demonstration anti-unification into portable JSON-Schema programs.\n- Remote MCP with the protocol paths currently documented below.\n- Browser WebMCP through `document.modelContext.registerTool()` with abortable registration generations and invocation cancellation.\n- Generic `/api/invoke` plus OpenAI-, Anthropic- and Gemini-style schema projections from the same canonical registry.\n- Bounded API bodies and canonical JSON-Schema argument validation.\n- No runtime npm dependencies in the current package.\n\n## Canonical API\n\nPublic HTTP surfaces:\n\n```text\nGET  /api/health\nGET  /api/capabilities\nGET  /api/search?query=web%20agents&limit=8\nPOST /api/invoke\nPOST /api/triage\nPOST /api/compile\nPOST /api/execute\nGET  /api/agents\nPOST /api/mcp\nGET  /api/openapi\n```\n\nCompatibility alias:\n\n```text\n/api/openalex/search → /api/search\n```\n\n### Generic invocation\n\n```http\nPOST /api/invoke\nContent-Type: application/json\n```\n\n```json\n{\n  \"name\": \"kata_search_research\",\n  \"arguments\": {\n    \"query\": \"web agents\",\n    \"limit\": 5\n  }\n}\n```\n\n## OpenAlex production configuration\n\nKATA works without a key, but authenticated OpenAlex usage can provide a materially larger allowance and account-specific usage telemetry.\n\nOptional server-side variable:\n\n```text\nOPENALEX_API_KEY\n```\n\nIt is sent only to `api.openalex.org` as an authorization credential and is not returned to clients.\n\nWhen the upstream provides rate-limit headers, KATA normalizes non-secret usage information under `meta.rateLimit` so callers can distinguish connector exhaustion from product failure.\n\n## Remote MCP\n\nKATA exposes remote MCP at:\n\n```text\nPOST /api/mcp\n```\n\nThe repository currently implements explicit paths for the protocol contracts documented by the checked-in release, including modern stateless request routing and compatibility with the earlier handshake-era path. See `GET /api/capabilities` for the machine-readable contract and the existing test suite for exact accepted/rejected envelopes.\n\nA modern tool call routes an explicit method and tool name and includes protocol metadata; KATA rejects disagreement rather than guessing caller intent.\n\nA valid tool call is:\n\n```http\nPOST /api/mcp\nContent-Type: application/json\nAccept: application/json, text/event-stream\nMCP-Protocol-Version: 2026-07-28\nMcp-Method: tools/call\nMcp-Name: kata_search_research\n```\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"research-1\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"kata_search_research\",\n    \"arguments\": {\n      \"query\": \"web agents\",\n      \"limit\": 5\n    },\n    \"_meta\": {\n      \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n      \"io.modelcontextprotocol/clientCapabilities\": {}\n    }\n  }\n}\n```\n\nOptional server variables:\n\n```text\nMCP_BEARER_TOKEN\nMCP_ALLOWED_ORIGINS\n```\n\n`MCP_BEARER_TOKEN` protects remote MCP with bearer authentication. Browser-origin remote MCP is default-deny when no origin allowlist is configured; non-browser MCP clients do not require an Origin header.\n\n## WebMCP\n\nKATA targets the current imperative browser producer API through `document.modelContext.registerTool()` when the browser provides it.\n\nRegistration generations share an `AbortController`; refreshing/disposal aborts stale registrations. Invocation `AbortSignal`s propagate into KATA's browser request path so cancelled search/automation/program executions do not commit partial workspace state.\n\nCross-origin exposure is opt-in. A deployment may provide exact trusted HTTPS origins through:\n\n```html\n<meta name=\"kata-webmcp-exposed-to\" content=\"https://agent.example,https://partner.example\">\n```\n\nMalformed origins, wildcards, credentials, paths, query strings and fragments are discarded. Stock deployment framing policy remains restrictive unless an operator deliberately changes it.\n\n## Product boundary\n\nKATA's browser triggers execute while KATA is open. The current release does **not** claim unattended cloud scheduling because it intentionally has no durable authenticated cloud workspace/runner.\n\nModern protocol calls are stateless: callers provide workspace snapshots and receive validated next snapshots. KATA does not hide a server-side session merely to make demos look stateful.\n\n## Run locally\n\nRequirement: Node.js 24.x.\n\n```bash\ngit clone https://github.com/dharan1007/kata.git\ncd kata\nnpm install\nnpm run check\n```\n\nThe current package declares no runtime dependencies.\n\n## Verification\n\n```bash\nnpm test\nnpm run build\nnpm run static-check\nnpm run check\n```\n\nProduction promotion should be treated separately from code verification: a green release gate does not turn a failed deployment into a successful one. Verify the canonical deployment and live APIs after promotion.\n\n## Security principles\n\n- No `eval`, `new Function`, arbitrary shell execution or generic URL-fetch agent tool.\n- Strict CSP with first-party scripts/styles/connections only.\n- Scholarly output is untrusted content and must be escaped before rendering.\n- External result links accept only HTTP(S).\n- API bodies are bounded.\n- Canonical JSON Schema validates tool arguments before handler execution.\n- Unsupported automation triggers are rejected rather than silently downgraded.\n- Cross-origin browser tool exposure is default-deny.\n\nSee [`SECURITY.md`](SECURITY.md) before changing protocol, connector or execution boundaries.\n\n## Contributing\n\nKATA needs connector fixtures, workflow examples, protocol compatibility tests, documentation and carefully bounded integrations. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md), [`good first issue`](https://github.com/dharan1007/kata/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), or [`help wanted`](https://github.com/dharan1007/kata/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).\n\n## Roadmap\n\nSee [`ROADMAP.md`](ROADMAP.md). The priority is to prove reusable workflow generalization and integration reliability before expanding into a catalogue of shallow connectors.\n\n## Related projects\n\n- [PACT](https://github.com/dharan1007/pact) — transactional safety for consequential agent actions.\n- [SPOOL](https://github.com/dharan1007/spool) — deterministic local-first data migration.\n- [FAULTLINE](https://github.com/dharan1007/faultline) — causal browser-failure reduction.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n\nIf KATA solves a workflow/research-automation problem you care about, star the repository to follow development and help other agent-tool builders discover it.",
  "bytes": 10040,
  "sha": "7d8c5289cdd3df2d6b1aa1a7c2ee256f2ba75bd4bb389047db19edaf3a89e787",
  "repo_slug": "dharan1007/kata",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dharan1007_kata_a601ac10/readme"
}