@towry/mcp 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# @towry/mcp
+
+MCP (Model Context Protocol) server for Knowledge Graph document management and Tmux pane control.
+
+## Installation
+
+```bash
+pnpm add @towry/mcp
+# or
+npm install @towry/mcp
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KG_API_URL` | Knowledge Graph API base URL | `http://localhost:8361` |
+| `KG_API_KEY` | API authentication key | `kg-dev-api-key` |
+| `KG_API_TOKEN` | Alternative to KG_API_KEY | - |
+
+## Usage
+
+### As a CLI
+
+```bash
+KG_API_URL=http://localhost:8361 pnpm dlx @towry/mcp
+```
+
+### With Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "towry-mcp-kg": {
+      "command": "npx",
+      "args": ["@towry/mcp"],
+      "env": {
+        "KG_API_URL": "http://localhost:8361",
+        "KG_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `kg_create_doc`
+
+Create or update a document in the knowledge graph.
+
+**Parameters:**
+- `title` (string, required): Document title
+- `body` (string, required): Document content
+- `doc_type` (enum, required): `note` | `doc` | `task` | `plan` | `agent_session`
+- `id` (string, optional): UUID to update existing doc
+- `project_repo` (string, optional): Project repo (owner/repo)
+- `tags` (string[], optional): Tags for categorization
+- `status` (enum, optional): `pending` | `in_progress` | `done` | `blocked` (for tasks)
+- `parent_id` (string, optional): Parent document ID for hierarchy
+
+### `kg_get_doc`
+
+Get full document by ID.
+
+**Parameters:**
+- `id` (string, required): Document UUID
+
+### `kg_delete_doc`
+
+Delete a document from the knowledge graph.
+
+**Parameters:**
+- `id` (string, required): Document UUID to delete
+
+### `kg_search`
+
+Search documents with filters.
+
+**Parameters:**
+- `q` (string, optional): Search query
+- `doc_type` (enum, optional): Filter by document type
+- `project_repo` (string, optional): Filter by project repo
+- `status` (enum, optional): Filter by task status
+- `tag` (string, optional): Filter by tag
+- `limit` (number, optional): Max results (1-100, default: 20)
+- `offset` (number, optional): Pagination offset (default: 0)
+
+### `kg_semantic_search`
+
+Semantic search using embeddings.
+
+**Parameters:**
+- `q` (string, required): Search query
+- `embedding_keywords` (string[], optional): Keywords for embedding search
+- `doc_type` (enum, optional): Filter by document type
+- `project_repo` (string, optional): Filter by project repo
+- `tag` (string, optional): Filter by tag
+- `limit` (number, optional): Max results (1-20, default: 5)
+
+### `kg_status`
+
+Get document statistics: total count, breakdown by type and repo.
+
+**Parameters:** None
+
+## Document Types
+
+| Type | Use Case |
+|------|----------|
+| `note` | Session-specific learnings, debugging discoveries (ephemeral) |
+| `doc` | Curated reference docs meant to be maintained (stable) |
+| `task` | Actionable items with status tracking |
+| `plan` | Multi-step roadmaps with phases |
+| `agent_session` | Chat session logs |
+
+## Tmux Tools
+
+### `tmux_list_panes`
+
+List all tmux panes.
+
+**Parameters:** None
+
+### `tmux_send`
+
+Send keys to a tmux pane.
+
+**Parameters:**
+- `pane` (string, optional): Target pane ID. Defaults to `PI_MASTER_PANE` env if set
+- `keys` (string, required): Keys to send
+- `enter` (boolean, optional): Send Enter after (default: true)
+
+### `tmux_kill_pane`
+
+Kill a tmux pane by ID.
+
+**Parameters:**
+- `pane` (string, required): Pane ID in `%N` format (e.g., `%886`)
+
+### `tmux_capture`
+
+Capture the content of a tmux pane.
+
+**Parameters:**
+- `pane` (string, required): Target pane ID to capture
+- `lines` (number, optional): Number of lines to capture from end (default: 10)
+- `filter` (string, optional): Grep pattern (case-insensitive, extended regex)
+
+### `tmux_run`
+
+Run a command in a new tmux pane with duplicate detection.
+
+**Parameters:**
+- `command` (string, required): Command to run
+- `name` (string, optional): Unique identifier for duplicate detection
+- `cwd` (string, optional): Working directory for the command
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Lint
+pnpm lint
+
+# Type check
+pnpm typecheck
+```
+
+## Debugging with MCP Inspector
+
+The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a browser-based tool for testing and debugging MCP servers.
+
+### Quick Start
+
+```bash
+# Using the package script (recommended)
+pnpm inspect
+
+# Or manually with environment variables
+pnpm dlx @modelcontextprotocol/inspector -e KG_API_URL=http://localhost:8361 -e KG_API_KEY=your-key node dist/index.js
+
+# Debug in watch mode (rebuild first, then run inspector)
+pnpm build && npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+### Inspector Features
+
+Once the inspector opens in your browser (default: http://localhost:6274):
+
+1. **Tools Tab**: List all available tools, view their schemas, and execute them with test parameters
+2. **Resources Tab**: Browse any resources exposed by the server
+3. **Prompts Tab**: Test prompt templates
+4. **Notifications Pane**: View real-time server notifications and logs
+
+### Development Workflow
+
+```bash
+# Terminal 1: Watch and rebuild on changes
+pnpm dev
+
+# Terminal 2: Run inspector (restart after rebuilds)
+pnpm inspect
+```
+
+### CLI Mode
+
+For quick testing without the browser UI:
+
+```bash
+pnpm dlx @modelcontextprotocol/inspector --cli node dist/index.js
+```
+
+### Debugging Tips
+
+- **Check tool schemas**: Use the Tools tab to verify parameter types and descriptions
+- **Test edge cases**: Try empty inputs, invalid types, missing required fields
+- **Monitor errors**: Watch the Notifications pane for server-side errors
+- **Verify API connectivity**: Test `kg_status` first to ensure the KG API is reachable
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @towry/mcp - Knowledge Graph & Tmux MCP Server
+ *
+ * Provides tools for:
+ * - Document management in a knowledge graph
+ * - Tmux pane management and control
+ *
+ * Environment Variables:
+ * - KG_API_URL: API base URL (default: http://localhost:8361)
+ * - KG_API_KEY or KG_API_TOKEN: API authentication key
+ *
+ * Keywords: mcp, knowledge-graph, document-management, tmux, ai-tools, llm-server
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/index.js

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+/**
+ * @towry/mcp - Knowledge Graph & Tmux MCP Server
+ *
+ * Provides tools for:
+ * - Document management in a knowledge graph
+ * - Tmux pane management and control
+ *
+ * Environment Variables:
+ * - KG_API_URL: API base URL (default: http://localhost:8361)
+ * - KG_API_KEY or KG_API_TOKEN: API authentication key
+ *
+ * Keywords: mcp, knowledge-graph, document-management, tmux, ai-tools, llm-server
+ */
+import { spawn } from "node:child_process";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TmuxCLI, getCurrentPaneInfo, shellQuote } from "./tmux.js";
+// ============================================================================
+// Knowledge Graph Types
+// ============================================================================
+const DocTypeEnum = z.enum(["note", "doc", "task", "plan", "agent_session"]);
+const TaskStatusEnum = z.enum(["pending", "in_progress", "done", "blocked"]);
+// ============================================================================
+// Knowledge Graph API Client
+// ============================================================================
+function getKgBaseUrl() {
+    return process.env.KG_API_URL ?? "http://localhost:8361";
+}
+function getKgApiKey() {
+    return process.env.KG_API_KEY ?? process.env.KG_API_TOKEN ?? "kg-dev-api-key";
+}
+async function kgApiRequest(method, path, body) {
+    const url = `${getKgBaseUrl()}${path}`;
+    const headers = {
+        "X-API-Key": getKgApiKey(),
+        "Content-Type": "application/json",
+    };
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ============================================================================
+// Tmux CLI Instance
+// ============================================================================
+const tmux = new TmuxCLI();
+const DEFAULT_CWD = process.cwd();
+// ============================================================================
+// MCP Server
+// ============================================================================
+const server = new McpServer({
+    name: "towry-mcp",
+    version: "0.1.0",
+});
+// ============================================================================
+// Knowledge Graph Tools
+// ============================================================================
+// kg_create_doc - Create or update a document
+server.registerTool("kg_create_doc", {
+    description: "Create or update a document. Use 'note' for session learnings (ephemeral), 'doc' for stable reference docs, 'plan' for roadmaps, 'task' for actionable items. For insights from current chat, prefer kg_insight_save.",
+    inputSchema: {
+        title: z.string().describe("Document title"),
+        body: z.string().describe("Document content"),
+        doc_type: DocTypeEnum.describe("note: session learnings (ephemeral), doc: stable reference, task: actionable items, plan: roadmaps, agent_session: chat logs"),
+        id: z.string().optional().describe("UUID to update existing doc"),
+        project_repo: z.string().optional().describe("Project repo (owner/repo)"),
+        tags: z.array(z.string()).optional().describe("Tags for categorization"),
+        status: TaskStatusEnum.optional().describe("Task status (only for task type)"),
+        parent_id: z.string().optional().describe("Parent document ID for hierarchy"),
+    },
+}, async (params) => {
+    const result = await kgApiRequest("POST", "/api/docs", {
+        ...params,
+        doc_type: params.doc_type ?? "note",
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// kg_get_doc - Get full document by ID
+server.registerTool("kg_get_doc", {
+    description: "Get full document by ID. Use AFTER kg_search when you need the complete body (snippets are truncated).",
+    inputSchema: {
+        id: z.string().describe("Document UUID"),
+    },
+}, async (params) => {
+    const result = await kgApiRequest("GET", `/api/docs/${params.id}`);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// kg_delete_doc - Delete a document
+server.registerTool("kg_delete_doc", {
+    description: "Delete a document from the knowledge graph.",
+    inputSchema: {
+        id: z.string().describe("Document UUID to delete"),
+    },
+}, async (params) => {
+    const result = await kgApiRequest("DELETE", `/api/docs/${params.id}`);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// kg_search - Search documents
+server.registerTool("kg_search", {
+    description: "Find plans, tasks, or docs. Use doc_type='plan' for plans, tag='insight' for insights. Returns snippets - use kg_get_doc for full content.",
+    inputSchema: {
+        q: z.string().optional().describe("Search query (optional - omit to list all of doc_type)"),
+        doc_type: DocTypeEnum.optional().describe("Filter by type: 'plan' for plans, 'note' for insights/learnings"),
+        project_repo: z.string().optional().describe("Filter by project repo"),
+        status: TaskStatusEnum.optional().describe("Filter by task status"),
+        tag: z.string().optional().describe("Filter by tag"),
+        limit: z.number().int().min(1).max(100).default(20).optional(),
+        offset: z.number().int().min(0).default(0).optional(),
+    },
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.q)
+        searchParams.set("q", params.q);
+    if (params.doc_type)
+        searchParams.set("doc_type", params.doc_type);
+    if (params.project_repo)
+        searchParams.set("project_repo", params.project_repo);
+    if (params.status)
+        searchParams.set("status", params.status);
+    if (params.tag)
+        searchParams.set("tag", params.tag);
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    if (params.offset)
+        searchParams.set("offset", String(params.offset));
+    const result = await kgApiRequest("GET", `/api/docs/search?${searchParams.toString()}`);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// kg_semantic_search - Semantic search using embeddings
+server.registerTool("kg_semantic_search", {
+    description: "Semantic search using embeddings in the knowledge graph.",
+    inputSchema: {
+        q: z.string().describe("Search query (required)"),
+        embedding_keywords: z
+            .array(z.string())
+            .optional()
+            .describe("Keywords for embedding search. If provided, searches with these keywords. If not, fetches latest 2 docs."),
+        doc_type: DocTypeEnum.optional().describe("Filter by document type"),
+        project_repo: z.string().optional().describe("Filter by project repo"),
+        tag: z.string().optional().describe("Filter by tag"),
+        limit: z.number().int().min(1).max(20).default(5).optional(),
+    },
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    const searchQuery = params.embedding_keywords && params.embedding_keywords.length > 0
+        ? params.embedding_keywords.join(" ")
+        : params.q;
+    searchParams.set("q", searchQuery);
+    if (params.doc_type)
+        searchParams.set("doc_type", params.doc_type);
+    if (params.project_repo)
+        searchParams.set("project_repo", params.project_repo);
+    if (params.tag)
+        searchParams.set("tag", params.tag);
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await kgApiRequest("GET", `/api/docs/semantic?${searchParams.toString()}`);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// kg_status - Get document statistics
+server.registerTool("kg_status", {
+    description: "Get document statistics: total count, breakdown by type (plan/task/doc/note) and by repo. Use to check what's stored before searching.",
+    inputSchema: {},
+}, async () => {
+    const result = await kgApiRequest("GET", "/api/docs/status");
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// ============================================================================
+// Tmux Tools
+// ============================================================================
+// tmux_list_panes - List all tmux panes
+server.registerTool("tmux_list_panes", {
+    description: "List all tmux panes",
+    inputSchema: {},
+}, async () => {
+    try {
+        const panes = await tmux.listTmuxPanes();
+        // Filter out current pane to prevent self-operations
+        const currentPane = process.env.TMUX_PANE || (await getCurrentPaneInfo()).id;
+        const filtered = currentPane ? panes.filter((p) => p.id !== currentPane) : panes;
+        return {
+            content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: String(err) }],
+            isError: true,
+        };
+    }
+});
+// tmux_send - Send keys to a pane
+server.registerTool("tmux_send", {
+    description: "Send keys to a tmux pane. If PI_MASTER_PANE env is set and pane is omitted, sends to master.",
+    inputSchema: {
+        pane: z.string().optional().describe("Target pane id. Defaults to PI_MASTER_PANE if set."),
+        keys: z.string().describe("Keys to send"),
+        enter: z.boolean().default(true).optional().describe("Send Enter after"),
+    },
+}, async (params) => {
+    const targetPane = params.pane || process.env.PI_MASTER_PANE;
+    if (!targetPane) {
+        return {
+            content: [{ type: "text", text: "pane is required (no PI_MASTER_PANE set)" }],
+            isError: true,
+        };
+    }
+    const currentPane = process.env.TMUX_PANE;
+    if (currentPane && targetPane === currentPane) {
+        return {
+            content: [{ type: "text", text: "cannot send keys to current pane" }],
+            isError: true,
+        };
+    }
+    try {
+        const paneInfo = await getCurrentPaneInfo();
+        const signature = paneInfo.id
+            ? ` [from ${paneInfo.id}${paneInfo.title ? `: ${paneInfo.title}` : ""}]`
+            : "";
+        const keysWithSig = params.keys + signature;
+        await tmux.sendTmuxKeys(keysWithSig, { pane: targetPane, enter: params.enter ?? true });
+        return {
+            content: [{ type: "text", text: "sent" }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: String(err) }],
+            isError: true,
+        };
+    }
+});
+// tmux_kill_pane - Kill a pane
+server.registerTool("tmux_kill_pane", {
+    description: "Kill a tmux pane by index (cannot close the last page)",
+    inputSchema: {
+        pane: z
+            .string()
+            .describe("Pane ID in %N format (e.g., %886). Do NOT use session:window.pane format - indices shift when panes are killed."),
+    },
+}, async (params) => {
+    // Reject volatile formatted IDs
+    if (params.pane.includes(":") || params.pane.includes(".")) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid pane ID format: "${params.pane}". Use stable %N format (e.g., %886), not session:window.pane format which shifts when panes are killed.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const normalize = (id) => (id.startsWith("%") ? id : `%${id}`);
+    const inputNorm = normalize(params.pane);
+    // Safety: prevent killing current pane
+    const envPane = process.env.TMUX_PANE;
+    if (envPane && inputNorm === normalize(envPane)) {
+        return {
+            content: [{ type: "text", text: "cannot kill current pane (self)" }],
+            isError: true,
+        };
+    }
+    if (!envPane) {
+        const currentInfo = await getCurrentPaneInfo();
+        if (currentInfo.id && inputNorm === normalize(currentInfo.id)) {
+            return {
+                content: [{ type: "text", text: "cannot kill current pane (self)" }],
+                isError: true,
+            };
+        }
+    }
+    try {
+        await tmux.killTmuxPane(inputNorm);
+        return {
+            content: [{ type: "text", text: "killed" }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: String(err) }],
+            isError: true,
+        };
+    }
+});
+// tmux_capture - Capture pane content
+server.registerTool("tmux_capture", {
+    description: "Capture the content of a tmux pane. Defaults to last 10 lines. Use filter for grep with context. Do not use this for polling.",
+    inputSchema: {
+        pane: z.string().describe("Target pane id to capture"),
+        lines: z.number().optional().describe("Number of lines to capture from end (default: 10)"),
+        filter: z
+            .string()
+            .optional()
+            .describe("Grep pattern (case-insensitive, extended regex). Use | for OR: 'error|fail|warning'"),
+    },
+}, async (params) => {
+    const currentPane = process.env.TMUX_PANE;
+    if (currentPane && params.pane === currentPane) {
+        return {
+            content: [{ type: "text", text: "cannot capture current pane" }],
+            isError: true,
+        };
+    }
+    try {
+        let output = await tmux.captureTmuxPane({ pane: params.pane, lines: params.lines ?? 10 });
+        if (params.filter?.trim()) {
+            const grepProc = spawn("grep", ["-i", "-E", "-C3", params.filter.trim()], {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            grepProc.stdin.write(output);
+            grepProc.stdin.end();
+            output = await new Promise((resolve) => {
+                let out = "";
+                grepProc.stdout.on("data", (d) => (out += d.toString()));
+                grepProc.on("close", () => resolve(out.trim()));
+            });
+        }
+        return {
+            content: [{ type: "text", text: output || "(no matching content)" }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: String(err) }],
+            isError: true,
+        };
+    }
+});
+// tmux_run - Run command in new pane
+server.registerTool("tmux_run", {
+    description: "Run a command in a new tmux pane. Checks for existing panes with same name to prevent duplicates (e.g., port conflicts).",
+    inputSchema: {
+        command: z.string().describe("Command to run"),
+        name: z
+            .string()
+            .optional()
+            .describe("Unique identifier for duplicate detection. If omitted, derived from command."),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory for the command. Defaults to current project cwd."),
+    },
+}, async (params) => {
+    if (!params.command?.trim()) {
+        return {
+            content: [{ type: "text", text: "command is required" }],
+            isError: true,
+        };
+    }
+    const workingDir = params.cwd || DEFAULT_CWD;
+    // Derive title
+    const cmdSlug = params.command
+        .trim()
+        .slice(0, 40)
+        .replace(/[^a-zA-Z0-9 _\-.]/g, "")
+        .trim();
+    const title = params.name?.trim()
+        ? `pi-run:${cmdSlug}:${params.name.trim()}`
+        : `pi-run:${cmdSlug}`;
+    try {
+        // Check for existing pane with same title
+        const panes = await tmux.listTmuxPanes();
+        const existing = panes.find((pane) => pane.title === title);
+        if (existing) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `pane "${title}" already exists: ${existing.id}. Kill it first to restart.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Build command with title setting
+        const startCommand = `cd ${shellQuote(workingDir)} && tmux set-option -p allow-set-title off && tmux select-pane -T ${shellQuote(title)} && ${params.command}`;
+        const paneId = await tmux.launchTmuxPane(startCommand, { vertical: true, size: 50 });
+        if (!paneId) {
+            return {
+                content: [{ type: "text", text: "launch failed" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: `started in pane ${paneId}. title: ${title}` }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: String(err) }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map