From f65a01b37328408242b97d4e143bcccb4aff9a6c Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Tue, 19 May 2026 00:39:11 +0200 Subject: [PATCH] docs: update agent client setup guidance --- README.md | 16 +++-- .../docs/integrations/agent-clients.mdx | 60 +++++++++++-------- 2 files changed, 47 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index be4027e6..d9df7377 100644 --- a/README.md +++ b/README.md @@ -108,9 +108,16 @@ ktx wiki search "refund policy" --json ktx sl query --connection-id warehouse --measure orders.revenue --format sql ``` -During agent setup, choose **MCP tools + analytics skill** for client agents. -Choose **MCP tools + analytics skill + admin CLI skill** only when a developer -or operator agent also needs pinned `ktx` admin commands. +During agent setup, choose **Ask data questions with KTX MCP** for client +agents. Choose **Ask data questions + manage KTX with CLI commands** only when +a developer or operator agent also needs pinned `ktx` admin commands. + +After setup, KTX prints **Required before using agents**. Complete those steps +before opening the configured agent. If it shows `ktx mcp start --project-dir ...`, +run that command before using Claude Code, Codex, Cursor, OpenCode, or generic +MCP clients. The same output also prints the matching `ktx mcp stop` command +for when you want to stop MCP later. Claude Desktop uses its own launcher and +only needs a restart. The analytics skill teaches client agents the MCP workflow: discover data, prefer semantic-layer measures, inspect entity details before raw SQL, and @@ -127,7 +134,8 @@ Supported client agents: Claude Code, Claude Desktop, Codex, Cursor, OpenCode, and clients that can use the printed MCP endpoint or `.agents` admin skills. Claude Desktop setup registers a local `ktx mcp stdio` server in Claude Desktop's config and generates `.ktx/agents/claude/ktx-plugin.zip` with the -analytics skill. +analytics skill. Restart Claude Desktop after setup; no manual plugin install +step is required. The release artifact manifest contains the public npm tarball and the bundled `kaelio-ktx` runtime wheel. The `python/ktx-sl` and `python/ktx-daemon` diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx index 1934c978..ecea5881 100644 --- a/docs-site/content/docs/integrations/agent-clients.mdx +++ b/docs-site/content/docs/integrations/agent-clients.mdx @@ -7,9 +7,9 @@ KTX exposes context to end-user agents through MCP tools. The CLI remains the admin surface for setup, ingest, status, daemon lifecycle, and debugging. Run `ktx setup` and select your client agent targets, or configure manually -using the snippets below. Choose **MCP tools + analytics skill** for client -agents. Choose **MCP tools + analytics skill + admin CLI skill** only when a -developer or operator agent also needs pinned `ktx` admin commands. +using the snippets below. Choose **Ask data questions with KTX MCP** for client +agents. Choose **Ask data questions + manage KTX with CLI commands** only when +a developer or operator agent also needs pinned `ktx` admin commands. ## Install with setup @@ -31,8 +31,8 @@ Use `--target` for one target: ktx setup --agents --target codex ``` -Use `--global` only with `claude-code` or `codex`. Claude Desktop always -generates a project-local plugin ZIP: +Use `--global` only with `claude-code` or `codex`. Claude Desktop always writes +global Claude Desktop config and generates a project-local plugin package: ```bash ktx setup --agents --target claude-code --global @@ -46,9 +46,9 @@ remove only files KTX installed. The interactive command asks two questions: ```txt -◆ How should client agents connect to this KTX project? -│ ○ MCP tools + analytics skill -│ ○ MCP tools + analytics skill + admin CLI skill +◆ What should agents be allowed to do with this KTX project? +│ ○ Ask data questions with KTX MCP +│ ○ Ask data questions + manage KTX with CLI commands └ ◆ Which agent targets should KTX install? @@ -66,18 +66,28 @@ also asks where to install supported agent config: ```txt ◆ Where should KTX install supported agent config? -│ ○ Project -│ ○ Global +│ +│ KTX project: /path/to/your/ktx-project +│ +│ ○ Project scope (KTX project directory) +│ ○ Global scope (user config) └ ``` ## Generated files -KTX writes MCP client configuration and an analytics skill by default. It writes -admin CLI skills only when you choose **MCP tools + analytics skill + admin CLI -skill**. +KTX writes MCP client configuration and analytics guidance by default. It writes +admin CLI guidance only when you choose **Ask data questions + manage KTX with +CLI commands**. -| Target | MCP tools + analytics skill | Adds with admin CLI skill | +After setup, KTX prints **Required before using agents**. Complete those steps +before opening the configured agent. If it shows `ktx mcp start --project-dir ...`, +run that command before using Claude Code, Codex, Cursor, OpenCode, or generic +MCP clients. The same output also prints the matching `ktx mcp stop` command +for when you want to stop MCP later. Claude Desktop uses its own launcher and +only needs a restart. + +| Target | Ask data questions with KTX MCP | Adds when agents can manage KTX with CLI | |--------|------------------------------|---------------------------| | Claude Code | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md` | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` stdio entry + `.ktx/agents/claude/ktx-plugin.zip` with analytics skill | Adds `skills/ktx/SKILL.md` inside the plugin ZIP | @@ -144,7 +154,7 @@ During setup, select **Cursor** from the agent targets. KTX writes: | Mode | File | |------|------| -| MCP tools + analytics skill | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` | +| Ask data questions with KTX MCP | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` | | Admin CLI rules | `.cursor/rules/ktx.mdc` | Cursor supports project-scoped installation only. @@ -168,8 +178,8 @@ same markdown command definitions. ## Claude Desktop During setup, select **Claude Desktop** from the agent targets. KTX writes the -MCP server entry directly into Claude Desktop's config and generates a separate -plugin ZIP for the analytics skill: +MCP server entry directly into Claude Desktop's config and prepares the +Claude Desktop skill package for the analytics workflow: - `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%AppData%/Claude/claude_desktop_config.json` (Windows) gets an @@ -178,13 +188,13 @@ plugin ZIP for the analytics skill: a usable Node.js (Volta, NVM, Homebrew, system) so Claude Desktop can spawn the server without needing `node` in PATH. - `.ktx/agents/claude/ktx-plugin.zip` contains the `ktx-analytics` skill (and - the admin `ktx` skill if you choose **MCP tools + analytics skill + admin - CLI skill**). Install the ZIP from Claude Desktop's plugin UI to load the - skill. + the admin `ktx` skill if you choose **Ask data questions + manage KTX with + CLI commands**). This package is generated by KTX setup; no manual plugin + install step is required. After `ktx setup`, restart Claude Desktop so it picks up the new MCP server -entry, then install the plugin ZIP. No daemon needs to be running — Claude -Desktop spawns the MCP server itself per session. +entry and bundled KTX skills. No daemon needs to be running — Claude Desktop +spawns the MCP server itself per session. Claude Desktop does not introspect local stdio MCP servers, so the per-tool "Connector"-style UI is not rendered for KTX. The tools are still callable @@ -192,7 +202,7 @@ from any Claude Desktop chat. If you move the KTX checkout or project directory, rerun `ktx setup --agents` to refresh the absolute paths in `claude_desktop_config.json` and the launcher -shim, then reinstall the regenerated plugin ZIP. +shim, then restart Claude Desktop. --- @@ -235,7 +245,7 @@ During setup, select **OpenCode** from the agent targets. KTX writes: | Mode | File | |------|------| -| MCP tools + analytics skill | Snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | +| Ask data questions with KTX MCP | Snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | | Admin CLI commands | `.opencode/commands/ktx.md` | OpenCode supports project-scoped installation only. @@ -282,6 +292,6 @@ Admin CLI skills call the same KTX CLI commands: | MCP tools | Yes | Local stdio via `claude_desktop_config.json` | Yes | Snippet | Snippet | | Analytics skill | `.claude/skills/ktx-analytics/SKILL.md` | Included in plugin ZIP | `.cursor/rules/ktx-analytics.mdc` | `.agents/skills/ktx-analytics/SKILL.md` | `.opencode/commands/ktx-analytics.md` | | Admin CLI skills | Optional | Optional in plugin ZIP | Optional (.mdc) | Optional | Optional | -| Global install | Yes | Project-local ZIP | No | Yes | No | +| Global install | Yes | Claude Desktop config | No | Yes | No | | Rule or instruction file | `.claude/rules/ktx.md` | Plugin `SETUP.md` | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` | | Skill file | `.claude/skills/ktx/SKILL.md` | `skills/ktx/SKILL.md` in plugin ZIP | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |