mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-01 08:59:39 +02:00
chore: move docs site workspace
This commit is contained in:
Andrey Avtomonov
parent
0ae9b6effd
commit
a46563bb01
52 changed files with 3 additions and 3 deletions
279
docs-site/content/docs/integrations/agent-clients.mdx
Normal file
279
docs-site/content/docs/integrations/agent-clients.mdx
Normal file
|
|
@ -0,0 +1,279 @@
|
|||
---
|
||||
title: Agent Clients
|
||||
description: Set up KTX with Claude Code, Cursor, Codex, and OpenCode.
|
||||
---
|
||||
|
||||
KTX integrates with coding agents through two channels that can be used independently or together:
|
||||
|
||||
- **MCP server** — A persistent Model Context Protocol server that exposes KTX tools (semantic queries, knowledge search, SQL execution) directly to the agent
|
||||
- **CLI skills** — Command definitions that teach the agent how to invoke KTX via the terminal
|
||||
|
||||
Run `ktx setup` and select your agent targets, or configure manually using the snippets below.
|
||||
|
||||
## Claude Code
|
||||
|
||||
### Install via `ktx setup`
|
||||
|
||||
During setup, select **Claude Code** from the agent targets. KTX writes:
|
||||
|
||||
| Mode | File |
|
||||
|------|------|
|
||||
| CLI skills | `.claude/skills/ktx/SKILL.md` |
|
||||
| MCP server | `.mcp.json` (under `mcpServers.ktx`) |
|
||||
|
||||
Both project-scoped and global installations are supported. Global installs write to `~/.claude/skills/ktx/SKILL.md`.
|
||||
|
||||
### Manual MCP configuration
|
||||
|
||||
Add KTX to `.mcp.json` at your project root:
|
||||
|
||||
```json title=".mcp.json"
|
||||
{
|
||||
"mcpServers": {
|
||||
"ktx": {
|
||||
"command": "ktx",
|
||||
"args": [
|
||||
"--project-dir", "/path/to/ktx-project",
|
||||
"serve",
|
||||
"--mcp", "stdio",
|
||||
"--semantic-compute",
|
||||
"--execute-queries"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `/path/to/ktx-project` with your KTX project directory. For a pinned local checkout, use the absolute path to the built CLI as the command and arguments generated by `ktx setup`.
|
||||
|
||||
### Manual CLI skills configuration
|
||||
|
||||
Create `.claude/skills/ktx/SKILL.md`:
|
||||
|
||||
```markdown title=".claude/skills/ktx/SKILL.md"
|
||||
---
|
||||
name: ktx
|
||||
description: Use local KTX semantic context, wiki knowledge, and safe SQL execution for this project.
|
||||
---
|
||||
|
||||
Available commands:
|
||||
- `ktx agent context --json --project-dir /path/to/project`
|
||||
- `ktx agent sl list --json --project-dir /path/to/project`
|
||||
- `ktx agent sl read '<sourceName>' --json --project-dir /path/to/project`
|
||||
- `ktx agent sl query --json --project-dir /path/to/project --connection-id '<id>' --query-file '<path>' --execute --max-rows 100`
|
||||
- `ktx agent wiki search '<query>' --json --project-dir /path/to/project`
|
||||
- `ktx agent wiki read '<pageId>' --json --project-dir /path/to/project`
|
||||
- `ktx agent sql execute --json --project-dir /path/to/project --connection-id '<id>' --sql-file '<path>' --max-rows 100`
|
||||
```
|
||||
|
||||
### Workflow tips
|
||||
|
||||
- Claude Code discovers skills automatically from `.claude/skills/` — no restart needed after setup
|
||||
- The MCP server starts on-demand when Claude Code first calls a KTX tool
|
||||
- Use `--semantic-compute` to enable query planning and execution
|
||||
- Global installation (`~/.claude/skills/ktx/SKILL.md`) makes KTX available in all projects without per-project setup
|
||||
|
||||
---
|
||||
|
||||
## Cursor
|
||||
|
||||
### Install via `ktx setup`
|
||||
|
||||
During setup, select **Cursor** from the agent targets. KTX writes:
|
||||
|
||||
| Mode | File |
|
||||
|------|------|
|
||||
| CLI rules | `.cursor/rules/ktx.mdc` |
|
||||
| MCP server | `.cursor/mcp.json` (under `mcpServers.ktx`) |
|
||||
|
||||
Cursor supports project-scoped installation only.
|
||||
|
||||
### Manual MCP configuration
|
||||
|
||||
Create or edit `.cursor/mcp.json`:
|
||||
|
||||
```json title=".cursor/mcp.json"
|
||||
{
|
||||
"mcpServers": {
|
||||
"ktx": {
|
||||
"command": "ktx",
|
||||
"args": [
|
||||
"--project-dir", "/path/to/ktx-project",
|
||||
"serve",
|
||||
"--mcp", "stdio",
|
||||
"--semantic-compute",
|
||||
"--execute-queries"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual CLI rules configuration
|
||||
|
||||
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 format with command definitions.
|
||||
|
||||
### Workflow tips
|
||||
|
||||
- After adding MCP config, restart Cursor or reload the window for the server to connect
|
||||
- Cursor rules in `.cursor/rules/` are automatically loaded into agent context
|
||||
- MCP tools appear in Cursor's tool list once the server is running
|
||||
- Project-scoped only — no global installation option
|
||||
|
||||
---
|
||||
|
||||
## Codex
|
||||
|
||||
### Install via `ktx setup`
|
||||
|
||||
During setup, select **Codex** from the agent targets. KTX writes:
|
||||
|
||||
| Mode | File |
|
||||
|------|------|
|
||||
| CLI skills | `.agents/skills/ktx/SKILL.md` |
|
||||
| MCP server | `.agents/mcp/ktx.json` (under `mcpServers.ktx`) |
|
||||
|
||||
Both project-scoped and global installations are supported. Global installs write to `$CODEX_HOME/skills/ktx/SKILL.md` (defaults to `~/.codex/skills/ktx/SKILL.md`).
|
||||
|
||||
### Manual MCP configuration
|
||||
|
||||
Create or edit `.agents/mcp/ktx.json`:
|
||||
|
||||
```json title=".agents/mcp/ktx.json"
|
||||
{
|
||||
"mcpServers": {
|
||||
"ktx": {
|
||||
"command": "ktx",
|
||||
"args": [
|
||||
"--project-dir", "/path/to/ktx-project",
|
||||
"serve",
|
||||
"--mcp", "stdio",
|
||||
"--semantic-compute",
|
||||
"--execute-queries"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual CLI skills configuration
|
||||
|
||||
Create `.agents/skills/ktx/SKILL.md` with the same content structure as Claude Code's SKILL.md.
|
||||
|
||||
### Workflow tips
|
||||
|
||||
- Set `CODEX_HOME` environment variable to customize the global installation directory
|
||||
- Codex shares the `.agents/` directory structure with the universal format — one install covers both
|
||||
- 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 |
|
||||
|------|------|
|
||||
| CLI commands | `.opencode/commands/ktx.md` |
|
||||
| MCP server | `.opencode/mcp.json` (under `mcpServers.ktx`) |
|
||||
|
||||
OpenCode supports project-scoped installation only.
|
||||
|
||||
### Manual MCP configuration
|
||||
|
||||
Create or edit `.opencode/mcp.json`:
|
||||
|
||||
```json title=".opencode/mcp.json"
|
||||
{
|
||||
"mcpServers": {
|
||||
"ktx": {
|
||||
"command": "ktx",
|
||||
"args": [
|
||||
"--project-dir", "/path/to/ktx-project",
|
||||
"serve",
|
||||
"--mcp", "stdio",
|
||||
"--semantic-compute",
|
||||
"--execute-queries"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual CLI commands configuration
|
||||
|
||||
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 — no global installation option
|
||||
- Commands file uses standard markdown format (`.md` extension)
|
||||
|
||||
---
|
||||
|
||||
## MCP server reference
|
||||
|
||||
All agent clients connect to the same KTX MCP server. The server exposes these tools:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `connection_list` | List configured database connections |
|
||||
| `connection_test` | Test a database connection |
|
||||
| `knowledge_search` | Semantic + full-text search across knowledge pages |
|
||||
| `knowledge_read` | Read a specific knowledge page |
|
||||
| `knowledge_write` | Write or update a knowledge page |
|
||||
| `sl_list_sources` | List semantic layer sources |
|
||||
| `sl_read_source` | Read a semantic source definition |
|
||||
| `sl_write_source` | Write or update a semantic source |
|
||||
| `sl_validate` | Validate a source against the database schema |
|
||||
| `sl_query` | Execute a semantic layer query |
|
||||
| `ingest_trigger` | Trigger an ingestion run |
|
||||
| `ingest_status` | Check ingestion status |
|
||||
| `ingest_report` | View an ingestion report |
|
||||
| `ingest_replay` | Replay a past ingestion session |
|
||||
| `scan_trigger` | Trigger a structural, enriched, or relationship scan |
|
||||
| `scan_status` | Check scan status |
|
||||
| `scan_report` | View a completed scan report |
|
||||
| `scan_list_artifacts` | List artifacts produced by a scan |
|
||||
| `scan_read_artifact` | Read a scan artifact |
|
||||
| `memory_capture` | Capture reusable context from an agent conversation when memory capture is enabled |
|
||||
| `memory_capture_status` | Check a memory capture run |
|
||||
|
||||
### Server flags
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--project-dir` | KTX project directory; otherwise KTX uses `KTX_PROJECT_DIR`, the nearest `ktx.yaml`, or the current directory | Auto-detected |
|
||||
| `--mcp stdio` | Transport mode (stdio only) | Required |
|
||||
| `--semantic-compute` | Enable semantic layer queries | `false` |
|
||||
| `--execute-queries` | Allow read-only SQL execution | `false` |
|
||||
| `--semantic-compute-url` | Remote compute endpoint URL | — |
|
||||
| `--database-introspection-url` | Live schema introspection endpoint | — |
|
||||
| `--memory-capture` | Record agent interactions | `false` |
|
||||
| `--memory-model` | LLM model for memory processing | — |
|
||||
|
||||
### Security constraints
|
||||
|
||||
- SQL execution is always read-only
|
||||
- Agent CLI SQL execution requires an explicit `--max-rows` limit from 1 to 1000; MCP semantic queries default to a 1000-row cap
|
||||
- Secrets and credentials are never exposed in tool responses
|
||||
- The server runs as a child process of the agent client (no network exposure)
|
||||
|
||||
---
|
||||
|
||||
## Comparison
|
||||
|
||||
| | Claude Code | Cursor | Codex | OpenCode |
|
||||
|---|---|---|---|---|
|
||||
| MCP support | Yes | Yes | Yes | Yes |
|
||||
| CLI skills | Yes | Yes (.mdc) | Yes | Yes |
|
||||
| Global install | Yes | No | Yes | No |
|
||||
| Config location | `.mcp.json` | `.cursor/mcp.json` | `.agents/mcp/ktx.json` | `.opencode/mcp.json` |
|
||||
| Skills location | `.claude/skills/` | `.cursor/rules/` | `.agents/skills/` | `.opencode/commands/` |
|
||||
Loading…
Add table
Add a link
Reference in a new issue