mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
e6d578c03f
* feat(setup): add Claude Desktop target and MCP-first agent setup Adds `ktx mcp stdio` and a `claude-desktop` setup target that generates a local plugin ZIP wiring the analytics skill and a stdio MCP config. Replaces the CLI-only agent install mode with MCP+analytics (default) and an optional admin CLI skill, renames the research skill to analytics, and lets interactive setup pick project vs global scope when every target supports it. Extracts a shared MCP server factory used by both HTTP and stdio entrypoints. * Add MCP agent client setup support * Polish setup output formatting * Add MCP tool polish design spec Design for slimming the MCP-registered surface from 25 to 11 tools, introducing memory_ingest, applying the per-tool polish kit (annotations, outputSchema, .describe(), in-band error wrapping, union-drift fixes, type-narrowed jsonToolResult), emitting progress notifications on sql_execution + sl_query, and refining the ktx-analytics SKILL.md to match. * Refine MCP tool polish design spec after adversarial review iteration 1 * Refine MCP tool polish design spec after adversarial review iteration 2 * Refine MCP tool polish design spec after adversarial review iteration 3 * refactor(context): rename memory capture service to ingest * feat(mcp): slim research tool surface * refactor(mcp): remove admin ports from server factory * refactor(cli): rename text ingest memory port * docs: update analytics skill for memory ingest * chore: verify mcp surface rename * Add MCP tool polish v1 surface change plan * feat(context): polish mcp tool metadata * fix(context): enforce resolved semantic layer compute sources * feat(context): emit mcp query progress stages * fix(context): keep mcp progress event internal * Add MCP tool polish v1 metadata & progress plan * Fix CI snapshot and docs checks
287 lines
11 KiB
Text
287 lines
11 KiB
Text
---
|
|
title: Agent Clients
|
|
description: Set up KTX with Claude Code, Claude Desktop, Cursor, Codex, and OpenCode.
|
|
---
|
|
|
|
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.
|
|
|
|
## Install with setup
|
|
|
|
Start the MCP server before connecting an end-user agent:
|
|
|
|
```bash
|
|
ktx mcp start
|
|
```
|
|
|
|
Then install client integration:
|
|
|
|
```bash
|
|
ktx setup --agents
|
|
```
|
|
|
|
Use `--target` for one target:
|
|
|
|
```bash
|
|
ktx setup --agents --target codex
|
|
```
|
|
|
|
Use `--global` only with `claude-code` or `codex`. Claude Desktop always
|
|
generates a project-local plugin ZIP:
|
|
|
|
```bash
|
|
ktx setup --agents --target claude-code --global
|
|
ktx setup --agents --target codex --global
|
|
```
|
|
|
|
KTX records installed files in `.ktx/agents/install-manifest.json`. That
|
|
manifest lets status checks report agent readiness and lets future cleanup
|
|
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
|
|
└
|
|
|
|
◆ Which agent targets should KTX install?
|
|
│ ◻ Claude Code
|
|
│ ◻ Claude Desktop
|
|
│ ◻ Codex
|
|
│ ◻ Cursor
|
|
│ ◻ OpenCode
|
|
│ ◻ Universal .agents
|
|
└
|
|
```
|
|
|
|
When every selected target supports both project and global setup, the command
|
|
also asks where to install supported agent config:
|
|
|
|
```txt
|
|
◆ Where should KTX install supported agent config?
|
|
│ ○ Project
|
|
│ ○ Global
|
|
└
|
|
```
|
|
|
|
## 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**.
|
|
|
|
| Target | MCP tools + analytics skill | Adds with admin CLI skill |
|
|
|--------|------------------------------|---------------------------|
|
|
| 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 |
|
|
| Codex | Printed snippet for `~/.codex/config.toml`, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
|
| Cursor | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` | `.cursor/rules/ktx.mdc` |
|
|
| OpenCode | Printed snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | `.opencode/commands/ktx.md` |
|
|
| Universal `.agents` | Printed MCP endpoint, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md` |
|
|
|
|
MCP config gives agents access to KTX context tools such as discovery,
|
|
semantic-layer queries, wiki search, SQL execution, and memory ingest. The
|
|
analytics skill explains how to use those tools for semantic-layer-first
|
|
analysis. Optional admin skill and rule files list pinned CLI commands for
|
|
developer or operator agents.
|
|
|
|
## Claude Code
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Claude Code** from the agent targets. KTX writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md`; optional `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
|
|
| Global | `~/.claude.json`, `~/.claude/skills/ktx-analytics/SKILL.md`; optional `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
|
|
|
Both project-scoped and global installations are supported.
|
|
|
|
### Manual CLI skills configuration
|
|
|
|
Use manual CLI skills only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.claude/skills/ktx/SKILL.md`:
|
|
|
|
```markdown title=".claude/skills/ktx/SKILL.md"
|
|
---
|
|
name: ktx
|
|
description: Use local KTX semantic context and wiki knowledge for this project.
|
|
---
|
|
|
|
Available commands:
|
|
- `ktx status --json --project-dir /path/to/project`
|
|
- `ktx sl list --json --project-dir /path/to/project`
|
|
- `ktx sl search '<text>' --json --project-dir /path/to/project --connection-id '<id>'`
|
|
- `ktx sl query --project-dir /path/to/project --connection-id '<id>' --query-file '<path>' --format json --execute --max-rows 100`
|
|
- `ktx wiki search '<query>' --json --project-dir /path/to/project --limit 10`
|
|
```
|
|
|
|
### Workflow tips
|
|
|
|
- Claude Code discovers skills automatically from `.claude/skills/`.
|
|
- Claude Code reads MCP config from `.mcp.json` for project-scoped MCP tools.
|
|
- Claude rules in `.claude/rules/` tell Claude when KTX should be used.
|
|
- Global installation makes KTX available in all projects without per-project setup.
|
|
- Keep generated skills committed only when your team wants project-local agent instructions in git.
|
|
|
|
---
|
|
|
|
## Cursor
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Cursor** from the agent targets. KTX writes:
|
|
|
|
| Mode | File |
|
|
|------|------|
|
|
| MCP tools + analytics skill | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` |
|
|
| Admin CLI rules | `.cursor/rules/ktx.mdc` |
|
|
|
|
Cursor supports project-scoped installation only.
|
|
|
|
### Manual CLI rules configuration
|
|
|
|
Use manual CLI rules only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.cursor/rules/ktx.mdc` with the same content structure as the Claude
|
|
Code `SKILL.md` file. Cursor rules use the `.mdc` extension but support the
|
|
same markdown command definitions.
|
|
|
|
### Workflow tips
|
|
|
|
- Cursor rules in `.cursor/rules/` are automatically loaded into agent context.
|
|
- Project-scoped installs keep KTX command guidance close to the analytics context repository.
|
|
|
|
---
|
|
|
|
## 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:
|
|
|
|
- `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
|
|
`%AppData%/Claude/claude_desktop_config.json` (Windows) gets an
|
|
`mcpServers.ktx` entry that runs the KTX MCP server over stdio via a local
|
|
launcher shim at `.ktx/agents/claude/ktx-plugin-runner.sh`. The shim locates
|
|
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.
|
|
|
|
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.
|
|
|
|
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
|
|
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.
|
|
|
|
---
|
|
|
|
## Codex
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Codex** from the agent targets. KTX writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | MCP snippet, `.agents/skills/ktx-analytics/SKILL.md`; optional `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
|
| Global | MCP snippet, `$CODEX_HOME/skills/ktx-analytics/SKILL.md`; optional `$CODEX_HOME/skills/ktx/SKILL.md`, `$CODEX_HOME/instructions/ktx.md` |
|
|
|
|
Both project-scoped and global installations are supported. `CODEX_HOME`
|
|
defaults to `~/.codex`.
|
|
|
|
### Manual CLI skills configuration
|
|
|
|
Use manual CLI skills only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.agents/skills/ktx/SKILL.md` with the same content structure as Claude
|
|
Code's `SKILL.md`.
|
|
|
|
### Workflow tips
|
|
|
|
- Set `CODEX_HOME` to customize the global installation directory.
|
|
- Codex shares the `.agents/` directory structure with the universal format.
|
|
- Codex instructions in `.codex/instructions/` tell Codex when KTX should be used.
|
|
- Global installation makes KTX available across all Codex sessions.
|
|
|
|
---
|
|
|
|
## OpenCode
|
|
|
|
### Install via `ktx setup`
|
|
|
|
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` |
|
|
| Admin CLI commands | `.opencode/commands/ktx.md` |
|
|
|
|
OpenCode supports project-scoped installation only.
|
|
|
|
### Manual CLI commands configuration
|
|
|
|
Use manual CLI commands only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.opencode/commands/ktx.md` with the same command definitions as Claude
|
|
Code's `SKILL.md`.
|
|
|
|
### Workflow tips
|
|
|
|
- OpenCode reads commands from `.opencode/commands/` on startup.
|
|
- Project-scoped only; use a shared repository template if multiple projects need identical command files.
|
|
|
|
---
|
|
|
|
## Command reference
|
|
|
|
Admin CLI skills call the same KTX CLI commands:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `ktx status --json` | Return project setup and context readiness |
|
|
| `ktx wiki search <query> --json` | Search wiki pages |
|
|
| `ktx sl list --json` | List semantic-layer sources |
|
|
| `ktx sl search <query> --json` | Search semantic-layer sources |
|
|
| `ktx sl validate <source> --connection-id <id>` | Validate semantic source definitions |
|
|
| `ktx sl query --format json` | Execute a semantic-layer query when semantic compute is configured |
|
|
|
|
### Security constraints
|
|
|
|
- Secrets and credentials are never exposed in command output.
|
|
- Commands resolve the project from `--project-dir`, `KTX_PROJECT_DIR`, or the nearest `ktx.yaml`.
|
|
|
|
---
|
|
|
|
## Comparison
|
|
|
|
| | Claude Code | Claude Desktop | Cursor | Codex | OpenCode |
|
|
|---|---|---|---|---|---|
|
|
| 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 |
|
|
| 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 |
|