openclacky 1.1.6 → 1.2.0

data/lib/clacky/default_skills/mcp-manager/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: mcp-manager
+description: |
+  Manage MCP (Model Context Protocol) servers for openclacky: add, list, probe, remove,
+  reconfigure. Edits ~/.clacky/mcp.json so the user never writes JSON by hand.
+  Trigger on: add mcp, install mcp, setup mcp, configure mcp, mcp list, mcp remove,
+  mcp probe, mcp reconfigure.
+argument-hint: "add | list | probe <name> | remove <name> | reconfigure <name>"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskFollowupQuestion
+---
+
+# MCP Manager Skill
+
+Manage MCP servers for openclacky. The user's MCP configuration lives at
+`~/.clacky/mcp.json` (the same format Claude Desktop and Cursor use). You never
+ask the user to edit it by hand — you do it for them through the local clacky
+HTTP API.
+
+---
+
+## Command Parsing
+
+| User says | Subcommand |
+|---|---|
+| `add mcp`, `install mcp`, `connect <something>`, "I want clacky to read my files / access github / query my db / search the web" | `add` |
+| `mcp list`, `mcp status`, "what mcps do I have" | `list` |
+| `mcp probe <name>`, "what tools does <name> have" | `probe` |
+| `mcp remove <name>`, `mcp delete <name>` | `remove` |
+| `mcp reconfigure <name>`, `mcp fix <name>` | `reconfigure` |
+
+If the intent is unclear, default to **`add`** — it's the most common ask.
+
+---
+
+## Server Coordinates
+
+All API calls go to the local clacky server. The host and port are exposed via
+environment variables:
+
+```bash
+HOST="${CLACKY_SERVER_HOST:-127.0.0.1}"
+PORT="${CLACKY_SERVER_PORT:-7070}"
+BASE="http://${HOST}:${PORT}"
+```
+
+All write operations require requests to come from `127.0.0.1` or `::1`. They
+will, because we're running locally.
+
+---
+
+## API Cheat Sheet
+
+| Action | Call |
+|---|---|
+| List configured servers | `curl -s ${BASE}/api/mcp` |
+| Add a server | `curl -s -X POST ${BASE}/api/mcp -H 'Content-Type: application/json' -d '{...}'` |
+| Update a server | `curl -s -X PUT ${BASE}/api/mcp/<name> -H 'Content-Type: application/json' -d '{...}'` |
+| Remove a server | `curl -s -X DELETE ${BASE}/api/mcp/<name>` |
+| Probe tools | `curl -s -X POST ${BASE}/api/mcp/<name>/probe` |
+
+Request body for create/update — **stdio** (local process, default):
+
+```json
+{
+  "name": "filesystem",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
+  "env": { "API_KEY": "xxx" },
+  "description": "Read/write files in ~/Documents"
+}
+```
+
+Request body for create/update — **http** (remote server, streamable-http):
+
+```json
+{
+  "name": "linear",
+  "type": "http",
+  "url":  "https://mcp.linear.app/sse",
+  "headers": { "Authorization": "Bearer lin_api_xxx" },
+  "description": "Linear issues and projects"
+}
+```
+
+If `type` is omitted but `url` is present, the server treats it as `http`.
+
+---
+
+## Known-Good Server Catalog
+
+When the user describes what they want, match it to one of these and propose it.
+Each entry: package, what it does, required params, recommended `description`.
+
+### 1. `filesystem` — read/write local files
+- **When**: "read my files", "access my desktop", "browse my code"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-filesystem", "<ABSOLUTE_PATH>"]`
+- **Required**: absolute directory path (ask user; default to `~/Documents`)
+- **Tools**: read_file, write_file, list_directory, search_files, etc.
+
+### 2. `github` — GitHub repos, issues, PRs
+- **When**: "access github", "manage my repos", "read my issues"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-github"]`
+- **Env**: `{ "GITHUB_PERSONAL_ACCESS_TOKEN": "<TOKEN>" }`
+- **Required**: PAT from https://github.com/settings/tokens (recommend `repo` scope)
+
+### 3. `fetch` — fetch HTTP URLs as markdown
+- **When**: "fetch web pages", "read articles by url"
+- **Command**: `uvx`
+- **Args**: `["mcp-server-fetch"]`
+- **Required**: nothing
+- **Note**: needs Python `uv` installed (`brew install uv`)
+
+### 4. `memory` — persistent knowledge graph
+- **When**: "remember things across sessions", "give clacky long-term memory"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-memory"]`
+- **Required**: nothing
+
+### 5. `postgres` — query a Postgres database
+- **When**: "query my database", "connect to postgres"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-postgres", "<DATABASE_URL>"]`
+- **Required**: DATABASE_URL like `postgresql://user:pass@host:5432/dbname`
+
+### 6. `slack` — Slack messages
+- **When**: "read slack", "send slack messages"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-slack"]`
+- **Env**: `{ "SLACK_BOT_TOKEN": "xoxb-...", "SLACK_TEAM_ID": "T..." }`
+- **Required**: bot token and team id (Slack admin → app config)
+
+### 7. `brave-search` — web search via Brave API
+- **When**: "search the web", "give clacky search"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-brave-search"]`
+- **Env**: `{ "BRAVE_API_KEY": "<KEY>" }`
+- **Required**: free API key from https://api.search.brave.com/
+
+### 8. `puppeteer` — browser automation
+- **When**: "automate the browser", "scrape with js"
+- **Command**: `npx`
+- **Args**: `["-y", "@modelcontextprotocol/server-puppeteer"]`
+- **Required**: nothing (downloads Chromium on first run)
+
+### Custom (anything else)
+If the user names a package or path you don't recognize, take the spec from them
+verbatim and pass it through. Always confirm `command`, `args`, and `env` back
+in plain language before saving.
+
+### Remote / HTTP servers (streamable-http)
+Some MCP servers are hosted services and don't ship as a CLI — you connect over
+HTTPS instead. **Trigger when** the user gives you a URL ending in `/mcp`,
+`/sse`, or hosted on `*.mcp.*` / `mcp.*.app`, or says "the server is at
+https://...".
+
+- **Type**: `http`
+- **Required**: `url` (the streamable-http endpoint)
+- **Optional**: `headers` — typically `{ "Authorization": "Bearer <token>" }`
+
+Examples of remote MCP servers in the wild:
+- Linear: `https://mcp.linear.app/sse` (Bearer API key)
+- Cloudflare: `https://<workers-subdomain>.workers.dev/mcp` (Bearer token)
+- GitHub Copilot: `https://api.githubcopilot.com/mcp/` (OAuth, advanced)
+
+When the user pastes a URL, ask:
+1. What service is this? (so you can pick a `name` and `description`)
+2. Does it need an authorization header? If yes, paste the token.
+
+Save with `type: "http"`. The local clacky never spawns a process for these —
+it just POSTs JSON-RPC over HTTPS.
+
+> ⚠️ Wrapping a regular CLI tool: if the user gives you a CLI command that is
+> **not** a stdio MCP server (e.g. `mcp-cli`, `some-api-cli login`), do NOT save
+> it as a stdio MCP entry — it won't speak JSON-RPC over stdin. Tell them: *"This
+> looks like a regular CLI, not an MCP server. Does the service offer an HTTPS
+> endpoint instead?"*
+
+---
+
+## Subcommand: `add` — the primary flow
+
+Goal: the user describes what they want, you produce a working MCP entry +
+confirm it works. Keep questions minimal.
+
+### Step 1 — Identify intent
+- If the user's first message already names a server (e.g. "add filesystem"),
+  pick that catalog entry directly.
+- Otherwise, ask **one** open question: *"What would you like Clacky to be
+  able to do? (e.g. read your files, access GitHub, search the web)"*
+- Match their answer to the catalog. If multiple match, present 2–3 options
+  with one-line descriptions and let them pick.
+
+### Step 2 — Environment preflight
+Before asking for parameters, check the runtime is installed:
+
+```bash
+# For npx-based servers
+which npx >/dev/null 2>&1 || echo "MISSING_NPX"
+
+# For uvx-based servers
+which uvx >/dev/null 2>&1 || echo "MISSING_UVX"
+```
+
+If missing, tell the user how to install (`brew install node` for npx,
+`brew install uv` for uvx) and stop. Do not proceed.
+
+### Step 3 — Collect parameters
+Ask only for the **business-meaningful** params from the catalog entry:
+- For `filesystem`: which directory? Default offer: `~/Documents`. Resolve `~`
+  to an absolute path before saving.
+- For `github`/`brave-search`/`slack`: tell them where to get the token, then
+  ask them to paste it.
+- For `postgres`: ask for the connection URL.
+
+Never invent values. If you don't have a sensible default, ask.
+
+### Step 4 — Confirm
+Show the user the spec you're about to save, in plain language:
+
+> I'll add a server called **filesystem** that runs `npx -y @modelcontextprotocol/server-filesystem /Users/me/Documents`. It'll let me read and write files in your Documents folder. OK?
+
+For secrets (tokens, passwords), echo only the last 4 characters: `***...abcd`.
+
+### Step 5 — Save
+For stdio:
+```bash
+curl -s -X POST ${BASE}/api/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "name":        "filesystem",
+        "command":     "npx",
+        "args":        ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
+        "description": "Read/write files in ~/Documents"
+      }'
+```
+
+For http:
+```bash
+curl -s -X POST ${BASE}/api/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "name":        "linear",
+        "type":        "http",
+        "url":         "https://mcp.linear.app/sse",
+        "headers":     { "Authorization": "Bearer lin_api_xxx" },
+        "description": "Linear issues and projects"
+      }'
+```
+
+If the response has `"ok": false`, show the error and ask the user how to
+proceed (retry, edit, abort).
+
+### Step 6 — Probe
+Immediately verify the server starts and exposes tools:
+
+```bash
+curl -s -X POST ${BASE}/api/mcp/filesystem/probe
+```
+
+- **`ok: true`**: extract `tools[]`, summarize for the user. Example:
+  > Done. **filesystem** is working — Clacky now has 11 new tools (read_file, write_file, list_directory, ...). Try asking me to *list files in your Documents folder*.
+- **`ok: false`**: show the error verbatim and offer common fixes:
+  - "command not found" → wrong runtime, suggest re-running with correct one
+  - "ENOENT" / "no such file" → bad path, ask for a valid one
+  - timeout → package may be downloading on first run; suggest retrying
+  - auth-related → token wrong/expired, offer `reconfigure`
+
+### Step 7 — Hint at next steps
+End with a one-line nudge: how the user can use the new MCP next. Examples:
+- filesystem: "Try: *list the files in my Documents folder*"
+- github: "Try: *show me my open PRs*"
+- fetch: "Try: *fetch https://news.ycombinator.com and summarize*"
+
+---
+
+## Subcommand: `list`
+
+```bash
+curl -s ${BASE}/api/mcp
+```
+
+Render as a short table. If `configured: false`, say so and offer to run `add`.
+
+```
+| Name         | Command | Args summary           | Has env |
+|--------------|---------|------------------------|---------|
+| filesystem   | npx     | @modelcontextprotocol… | no      |
+| github       | npx     | @modelcontextprotocol… | yes     |
+```
+
+Don't show full args if they contain absolute paths — collapse them with `…`.
+
+---
+
+## Subcommand: `probe <name>`
+
+```bash
+curl -s -X POST ${BASE}/api/mcp/<name>/probe
+```
+
+If `ok: true`, list every tool with a one-line description. If `ok: false`, run
+the same error-fixing flow as in `add` step 6.
+
+---
+
+## Subcommand: `remove <name>`
+
+1. Confirm with the user first: *"Remove **<name>**? Its tools will no longer
+   be available to Clacky. (Y/n)"*
+2. On yes:
+   ```bash
+   curl -s -X DELETE ${BASE}/api/mcp/<name>
+   ```
+3. Confirm completion in one line.
+
+---
+
+## Subcommand: `reconfigure <name>`
+
+1. Fetch current spec from `/api/mcp` and show it back.
+2. Ask which fields to change (path / token / args).
+3. Build the new spec and `PUT /api/mcp/<name>`.
+4. Probe to verify, same as `add` step 6.
+
+---
+
+## General Rules
+
+- **Never write directly to `~/.clacky/mcp.json`.** Always go through the API.
+- **Never echo full secrets.** Mask all but last 4 chars of tokens/URLs.
+- **One question at a time.** Don't dump a form on the user.
+- **Stop on errors.** Don't proceed past a failed preflight or probe.
+- **Quote real error messages.** Don't paraphrase API errors — users may need to
+  google them.
+- **Stay in scope.** If the user wants to write/edit a non-MCP file or do
+  unrelated work, hand back to the main agent.

data/lib/clacky/idle_compression_timer.rb

@@ -14,8 +14,10 @@ module Clacky
   #   timer.start   # call after each agent run completes
   #   timer.cancel  # call when new user input arrives
   class IdleCompressionTimer
-    # Seconds of inactivity before idle compression is triggered
-    IDLE_DELAY = 180
+    # Seconds of inactivity before idle compression is triggered.
+    # Kept under the 5-minute prompt cache TTL so the compression call itself
+    # still hits the existing prefix cache.
+    IDLE_DELAY = 314
 
     # @param agent [Clacky::Agent] the agent whose messages will be compressed
     # @param session_manager [Clacky::SessionManager, nil] used to persist session after compression

data/lib/clacky/mcp/client.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+
+require_relative "transport"
+require_relative "stdio_transport"
+require_relative "http_transport"
+
+module Clacky
+  module Mcp
+    # JSON-RPC 2.0 client for a single MCP server.
+    #
+    # Lifecycle: open transport on #start, send `initialize` handshake, then any
+    # number of `tools/list` / `tools/call` requests, then #stop closes the
+    # transport. Transport is selected by spec["type"]: "stdio" (default) or "http".
+    class Client
+      class McpError < StandardError; end
+      TransportError = Mcp::Transport::TransportError
+      class ProtocolError < McpError; end
+
+      DEFAULT_TIMEOUT = 30
+      INIT_TIMEOUT    = 15
+
+      PROTOCOL_VERSION = "2024-11-05"
+
+      attr_reader :name, :tools, :server_info, :started_at, :last_used_at
+
+      # Build a Client from an mcp.json spec hash.
+      # Recognized fields:
+      #   stdio: command (required), args, env, cwd
+      #   http:  type: "http", url (required), headers
+      def self.from_spec(name, spec)
+        type = (spec["type"] || (spec["url"] ? "http" : "stdio")).to_s
+        case type
+        when "stdio"
+          new(
+            name:    name,
+            transport: StdioTransport.new(
+              name:    name,
+              command: spec["command"],
+              args:    Array(spec["args"]),
+              env:     spec["env"] || {},
+              cwd:     spec["cwd"]
+            )
+          )
+        when "http", "streamable-http"
+          new(
+            name:    name,
+            transport: HttpTransport.new(
+              name:    name,
+              url:     spec["url"],
+              headers: spec["headers"] || {}
+            )
+          )
+        else
+          raise McpError, "unsupported MCP transport type '#{type}' for server '#{name}'"
+        end
+      end
+
+      def initialize(name:, transport: nil, command: nil, args: [], env: {}, cwd: nil)
+        @name = name
+        @transport = transport || StdioTransport.new(name: name, command: command, args: args, env: env, cwd: cwd)
+
+        @pending = {}
+        @next_id = 0
+        @lock    = Monitor.new
+        @started = false
+
+        @tools       = []
+        @server_info = nil
+        @started_at  = nil
+        @last_used_at = nil
+
+        @transport.on_message do |msg|
+          if msg["__transport_closed__"]
+            @lock.synchronize do
+              @pending.each_value { |q| q.push({ "error" => { "code" => -32000, "message" => "transport closed" } }) }
+              @pending.clear
+            end
+            next
+          end
+
+          id = msg["id"]
+          if id && (queue = @lock.synchronize { @pending.delete(id) })
+            queue.push(msg)
+          end
+        end
+      end
+
+      def started?
+        @started
+      end
+
+      def start
+        already_started = false
+        @lock.synchronize do
+          if @started
+            already_started = true
+          else
+            @transport.start
+          end
+        end
+        return self if already_started
+
+        handshake
+        fetch_tools
+
+        @lock.synchronize do
+          @started = true
+          @started_at = Time.now
+          @last_used_at = @started_at
+        end
+        self
+      end
+
+      def stop
+        @lock.synchronize do
+          @transport.stop rescue nil
+          @started = false
+        end
+      end
+
+      def tool_definitions
+        @tools.map do |t|
+          {
+            type: "function",
+            function: {
+              name: t["name"],
+              description: t["description"].to_s,
+              parameters: t["inputSchema"] || { type: "object", properties: {} }
+            }
+          }
+        end
+      end
+
+      def call_tool(tool_name, arguments = {})
+        ensure_started!
+        @last_used_at = Time.now
+        request("tools/call", { name: tool_name, arguments: arguments || {} })
+      end
+
+      def stderr_tail(bytes: 4096)
+        @transport.stderr_tail(bytes: bytes)
+      end
+
+      private def ensure_started!
+        raise TransportError, "MCP client '#{@name}' is not started" unless @started
+        raise TransportError, "MCP server '#{@name}' transport closed" unless @transport.alive?
+      end
+
+      private def handshake
+        result = request("initialize", {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities:    { tools: {} },
+          clientInfo:      { name: "openclacky", version: Clacky::VERSION }
+        }, timeout: INIT_TIMEOUT)
+
+        @server_info = result["serverInfo"]
+        notify("notifications/initialized")
+      end
+
+      private def fetch_tools
+        result = request("tools/list", {})
+        @tools = result["tools"] || []
+      end
+
+      private def request(method, params, timeout: DEFAULT_TIMEOUT)
+        id = nil
+        queue = Queue.new
+        @lock.synchronize do
+          id = (@next_id += 1)
+          @pending[id] = queue
+        end
+
+        payload = { jsonrpc: "2.0", id: id, method: method, params: params }
+        @transport.send_message(payload)
+
+        msg = nil
+        begin
+          require "timeout"
+          msg = Timeout.timeout(timeout) { queue.pop }
+        rescue Timeout::Error
+          msg = nil
+        end
+
+        if msg.nil?
+          @lock.synchronize { @pending.delete(id) }
+          raise TransportError, "MCP request '#{method}' to '#{@name}' timed out after #{timeout}s"
+        end
+
+        if (err = msg["error"])
+          raise ProtocolError, "MCP server '#{@name}' error on #{method}: #{err["message"]} (code #{err["code"]})"
+        end
+
+        msg["result"] || {}
+      end
+
+      private def notify(method, params = {})
+        @transport.send_message({ jsonrpc: "2.0", method: method, params: params })
+      end
+    end
+  end
+end