@sudosandwich/limps 2.13.3 → 3.1.0

package/README.md

@@ -19,6 +19,7 @@
 - [How You Can Use It](#how-you-can-use-it)
 - [Why limps?](#why-limps)
 - [Installation](#installation)
+- [Upgrading from v2](#upgrading-from-v2)
 - [Project Setup](#project-setup)
 - [Client Setup](#client-setup)
 - [Transport](#transport)
@@ -33,7 +34,6 @@
 - [Used in Production](#used-in-production)
 - [Creating a feature plan](#creating-a-feature-plan)
 - [Deep Dive](#deep-dive)
-- [Instructions](#instructions)
 - [What is MCP?](#what-is-mcp)
 - [License](#license)
 
@@ -43,15 +43,19 @@
 # Install globally
 npm install -g @sudosandwich/limps
 
-# Initialize a project
-limps init my-project --docs-path ~/Documents/my-planning-docs
+# Initialize in your project
+cd ~/Documents/my-planning-docs
+limps init
 
-# Add to your AI assistant (picks up all registered projects)
-limps config sync-mcp --client cursor
-limps config sync-mcp --client claude-code
+# Start the HTTP daemon
+limps start
+
+# Generate MCP client config
+limps config print --client claude-code
+# Copy the output to your MCP client config file
 ```
 
-Run this in the folder where you want to keep the docs and that's it. Your AI assistant now has access to your documents and nothing else. The folder can be anywhere—local, synced, or in a repo; limps does not require a git repository or a `plans/` directory.
+That's it. Your AI assistant now has access to your documents via HTTP transport. The folder can be anywhere—local, synced, or in a repo; limps does not require a git repository or a `plans/` directory.
 
 ## Features
 
@@ -59,7 +63,7 @@ Run this in the folder where you want to keep the docs and that's it. Your AI as
 - **Plan + agent workflows** with status tracking and task scoring
 - **Next-task suggestions** with score breakdowns and bias tuning
 - **Sandboxed document processing** via `process_doc(s)` helpers
-- **Multi-client sync** for Cursor, Claude, Codex, and more
+- **Multi-client support** for Cursor, Claude, Codex, and more
 - **Extensions** for domain-specific tooling (e.g., limps-headless)
 - **Knowledge graph** — Entity extraction, hybrid retrieval, conflict detection, and graph-based suggestions
 - **Health automation** — Staleness detection, code drift checks, status inference, and auto-fix proposals
@@ -81,7 +85,7 @@ Typical flow:
 
 1. Point limps at a docs directory (any folder, local or synced).
 2. Use CLI + MCP tools to create plans/docs, read the current status, update tasks, and close work when done.
-3. Sync MCP configs so Cursor/Claude/Codex all see the same plans.
+3. Add the limps MCP entry to each client config so Cursor/Claude/Codex all see the same plans.
 
 Commands and tools I use most often:
 
@@ -100,7 +104,7 @@ Full lists are below in "CLI Commands" and "MCP Tools."
 Common setups:
 
 - **Single project**: One docs folder for a product.
-- **Multi-project**: Register multiple folders and switch with `limps config use`.
+- **Multi-project**: Each project gets its own `.limps/config.json`; pass `--config` to target a specific one.
 - **Shared team folder**: Put plans in a shared location and review changes like code.
 - **Local-first**: Keep everything on disk, no hosted service required.
 
@@ -115,75 +119,96 @@ Key ideas:
 
 **The solution:** limps provides a standardized MCP interface that any tool can access. Your docs live in one place—a folder you choose. Use git (or any sync) if you want version control; limps is not tied to a repository.
 
-### Supported Clients
-
-| Client             | Config Location            | Command                                          |
-| ------------------ | -------------------------- | ------------------------------------------------ |
-| **Cursor**         | `.cursor/mcp.json` (local) | `limps config sync-mcp --client cursor`          |
-| **Claude Code**    | `.mcp.json` (local)        | `limps config sync-mcp --client claude-code`     |
-| **Claude Desktop** | Global config              | `limps config sync-mcp --client claude --global` |
-| **OpenAI Codex**   | `~/.codex/config.toml`     | `limps config sync-mcp --client codex --global`  |
-| **ChatGPT**        | Manual setup               | `limps config sync-mcp --client chatgpt --print` |
-
-> **Note:** By default, `sync-mcp` writes to local/project configs. Use `--global` for user-level configs.
-
 ## Installation
 
 ```bash
 npm install -g @sudosandwich/limps
 ```
 
+## Upgrading from v2
+
+v3 introduces major changes:
+
+### HTTP Transport (Breaking Change)
+
+v3 uses **HTTP transport exclusively**. stdio transport has been removed.
+
+**Migration steps:**
+
+1. **Start the HTTP daemon** for each project:
+   ```bash
+   limps start --config /path/to/.limps/config.json
+   ```
+
+2. **Update MCP client configs** — Replace stdio configs with HTTP transport:
+   ```json
+   {
+     "mcpServers": {
+       "limps-planning-myproject": {
+         "transport": {
+           "type": "http",
+           "url": "http://127.0.0.1:4269/mcp"
+         }
+       }
+     }
+   }
+   ```
+   Use `limps config print` to generate the correct snippet.
+
+### Per-Project Configs (Breaking Change)
+
+v3 removes the centralized project registry. If you previously used `limps config add`, `config use`, or the `--project` flag:
+
+1. **Run `limps init`** in each project directory to create `.limps/config.json`.
+2. **Update MCP client configs** — Replace `--project <name>` with HTTP transport config (see above).
+3. **Remove environment variable** — `LIMPS_PROJECT` no longer exists. Use `MCP_PLANNING_CONFIG` to override config path.
+
+**Removed commands:** `config list`, `config use`, `config add`, `config remove`, `config set`, `config discover`, `config migrate`, `config sync-mcp`, `serve`.
+
+**Replaced by:** `limps init` + `limps start` + `limps config print`.
+
 ## Project Setup
 
 ### Initialize a New Project
 
 ```bash
-limps init my-project --docs-path ~/Documents/my-planning-docs
+cd ~/Documents/my-planning-docs
+limps init
 ```
 
-This creates a config file and outputs setup instructions.
+This creates `.limps/config.json` in the current directory and prints MCP client setup instructions.
 
-### Register an Existing Directory
+You can also specify a path:
 
 ```bash
-limps config add my-project ~/Documents/existing-docs
+limps init ~/Documents/my-planning-docs
 ```
 
 If the directory contains a `plans/` subdirectory, limps uses it. Otherwise, it indexes the entire directory.
 
 ### Multiple Projects
 
-```bash
-# Register multiple projects
-limps init project-a --docs-path ~/docs/project-a
-limps init project-b --docs-path ~/docs/project-b
-
-# Switch between them
-limps config use project-a
+Each project has its own `.limps/config.json`. Use `--config` to target a specific project:
 
-# Or use environment variable
-LIMPS_PROJECT=project-b limps list-plans
+```bash
+limps list-plans --config ~/docs/project-b/.limps/config.json
 ```
 
 ## Client Setup
 
-### Automatic (Recommended)
+After running `limps init`, you need to add a limps entry to your MCP client's config file. Use `limps config print` to generate the correct snippet for your client, then paste it into the appropriate config file:
 
 ```bash
-# Add all projects to a client's local config
-limps config sync-mcp --client cursor
-
-# Preview changes without writing
-limps config sync-mcp --client cursor --print
+limps config print --client cursor
+limps config print --client claude-code
+limps config print --client claude
+```
 
-# Write to global config instead of local
-limps config sync-mcp --client cursor --global
+The output tells you exactly what JSON (or TOML) to add and where the config file lives.
 
-# Custom config path
-limps config sync-mcp --client cursor --path ./custom-mcp.json
-```
+### Per-Client Examples
 
-### Manual Setup
+All clients connect to the HTTP daemon. Start the daemon first with `limps start`, then configure your client.
 
 <details>
 <summary><b>Cursor</b></summary>
@@ -193,9 +218,11 @@ Add to `.cursor/mcp.json` in your project:
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "limps",
-      "args": ["serve", "--config", "/path/to/config.json"]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -211,9 +238,11 @@ Add to `.mcp.json` in your project root:
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "limps",
-      "args": ["serve", "--config", "/path/to/config.json"]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -224,48 +253,16 @@ Add to `.mcp.json` in your project root:
 <details>
 <summary><b>Claude Desktop</b></summary>
 
-Claude Desktop runs in a sandbox—use `npx` instead of global binaries.
-
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@sudosandwich/limps",
-        "serve",
-        "--config",
-        "/path/to/config.json"
-      ]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Windows (npx)</b></summary>
-
-On Windows, use `cmd /c` to run `npx`:
-
-```json
-{
-  "mcpServers": {
-    "limps": {
-      "command": "cmd",
-      "args": [
-        "/c",
-        "npx",
-        "-y",
-        "@sudosandwich/limps",
-        "serve",
-        "--config",
-        "C:\\path\\to\\config.json"
-      ]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -279,9 +276,9 @@ On Windows, use `cmd /c` to run `npx`:
 Add to `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.limps]
-command = "limps"
-args = ["serve", "--config", "/path/to/config.json"]
+[mcp_servers.limps-planning-myproject.transport]
+type = "http"
+url = "http://127.0.0.1:4269/mcp"
 ```
 
 </details>
@@ -289,26 +286,87 @@ args = ["serve", "--config", "/path/to/config.json"]
 <details>
 <summary><b>ChatGPT</b></summary>
 
-ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTP/SSE proxy.
+ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTPS reverse proxy (nginx, Caddy, etc.) with authentication.
 
 In ChatGPT → Settings → Connectors → Add custom connector:
 
 - **Server URL**: `https://your-domain.example/mcp`
-- **Authentication**: Configure as needed
+- **Authentication**: Configure as needed for your proxy
 
 Print setup instructions:
 
 ```bash
-limps config sync-mcp --client chatgpt --print
+limps config print --client chatgpt
 ```
 
 </details>
 
 ## Transport
 
-- **Current**: stdio (local MCP server, launched by your client).
-- **Remote clients**: Use an MCP-compatible proxy for HTTPS clients (e.g., ChatGPT).
-- **Roadmap**: SSE/HTTP transports are planned but not implemented yet.
+limps v3 uses **HTTP transport exclusively** via a persistent daemon. This allows multiple MCP clients to share a single server instance, avoiding file descriptor bloat from multiple stdio processes.
+
+### Start the HTTP daemon
+
+```bash
+# Start the daemon
+limps start --config /path/to/config.json
+
+# Check status (shows uptime, sessions, PID)
+limps status-server --config /path/to/config.json
+
+# Stop the daemon
+limps stop --config /path/to/config.json
+```
+
+The daemon runs at `http://127.0.0.1:4269/mcp` by default. Use `limps config print` to generate the correct MCP client configuration:
+
+```bash
+limps config print --client claude-code --config /path/to/config.json
+```
+
+### MCP Client Configuration
+
+All clients use HTTP transport. Example config:
+
+```json
+{
+  "mcpServers": {
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
+    }
+  }
+}
+```
+
+### Server Config Options
+
+Customize the HTTP server by adding a `"server"` section to your `config.json`:
+
+| Option             | Default        | Description                              |
+| ------------------ | -------------- | ---------------------------------------- |
+| `port`             | `4269`         | HTTP listen port                         |
+| `host`             | `127.0.0.1`   | Bind address                             |
+| `maxSessions`      | `100`          | Maximum concurrent MCP sessions          |
+| `sessionTimeoutMs` | `1800000`      | Session idle timeout in ms (30 min)      |
+| `corsOrigin`       | `""` (none)    | CORS origin (`""`, `"*"`, or a URL)      |
+| `maxBodySize`      | `10485760`     | Max request body in bytes (10 MB)        |
+| `rateLimit`        | `100 req/min`  | Rate limit per client IP                 |
+
+Example custom server config:
+
+```json
+{
+  "server": {
+    "port": 8080,
+    "host": "0.0.0.0"
+  }
+}
+```
+
+- **Remote clients**: Use an MCP-compatible HTTPS proxy for remote clients (e.g., ChatGPT).
 
 ## CLI Commands
 
@@ -324,12 +382,12 @@ limps next-task <plan>        # Get highest-priority available task
 ### Project Management
 
 ```bash
-limps init <name>             # Initialize new project
-limps serve                   # Start MCP server
-limps config list             # Show registered projects
-limps config use <name>       # Switch active project
+limps init [path]             # Initialize new project
+limps start                   # Start HTTP daemon (required for MCP clients)
+limps stop                    # Stop HTTP daemon
+limps status-server           # Show HTTP daemon status
 limps config show             # Display current config
-limps config sync-mcp         # Add projects to MCP clients
+limps config print            # Print MCP client config snippets
 ```
 
 ### Health & Automation
@@ -368,22 +426,16 @@ limps repair-plans [--fix]       # Check/fix agent frontmatter
 
 ## Configuration
 
-Config location varies by OS:
-
-| OS      | Path                                              |
-| ------- | ------------------------------------------------- |
-| macOS   | `~/Library/Application Support/limps/config.json` |
-| Linux   | `~/.config/limps/config.json`                     |
-| Windows | `%APPDATA%\limps\config.json`                     |
+Config lives at `.limps/config.json` in your project directory, created by `limps init`.
 
 ### Config Options
 
 ```json
 {
-  "plansPath": "~/Documents/my-plans",
-  "docsPaths": ["~/Documents/my-plans"],
+  "plansPath": "./plans",
+  "docsPaths": ["."],
   "fileExtensions": [".md"],
-  "dataPath": "~/Library/Application Support/limps/data",
+  "dataPath": ".limps/data",
   "extensions": ["@sudosandwich/limps-headless"],
   "tools": {
     "allowlist": ["list_docs", "search_docs"]
@@ -404,6 +456,7 @@ Config location varies by OS:
 | `tools`          | Tool allowlist/denylist filtering                          |
 | `extensions`     | Extension packages to load                                 |
 | `scoring`        | Task prioritization weights and biases                     |
+| `server`         | HTTP daemon settings (port, host, CORS, sessions, timeout) |
 | `graph`          | Knowledge graph settings (e.g., entity extraction options) |
 | `retrieval`      | Search recipe configuration for hybrid retrieval           |
 
@@ -411,7 +464,7 @@ Config location varies by OS:
 
 | Variable               | Description                                                | Example                                           |
 | ---------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
-| `LIMPS_PROJECT`        | Select active project for CLI commands                     | `LIMPS_PROJECT=project-b limps list-plans`        |
+| `MCP_PLANNING_CONFIG`  | Path to config file (overrides default discovery)          | `MCP_PLANNING_CONFIG=./my-config.json limps serve`|
 | `LIMPS_ALLOWED_TOOLS`  | Comma-separated allowlist; only these tools are registered | `LIMPS_ALLOWED_TOOLS="list_docs,search_docs"`     |
 | `LIMPS_DISABLED_TOOLS` | Comma-separated denylist; tools to hide                    | `LIMPS_DISABLED_TOOLS="process_doc,process_docs"` |