lcode-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/.github/ISSUE_TEMPLATE/model_request.yml

@@ -35,6 +35,11 @@ body:
       description: Context size used, tokens/s, whether tool calls (reading, editing, running commands) worked reliably, and anything odd.
     validations:
       required: true
+  - type: textarea
+    id: bench
+    attributes:
+      label: Output of `lcode bench <model> --markdown`
+      description: Optional, but the most useful thing you can add. It takes a few minutes; see https://nasser1941.github.io/lcode/bench/
   - type: textarea
     id: doctor
     attributes:

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/CHANGELOG.md

@@ -6,6 +6,43 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-01
+
+### Added
+
+- MCP (Model Context Protocol) servers: the model can use tools from Jira, GitHub, AWS, databases and
+  more, with your approval for every call.
+  - `lcode mcp add <name>` sets up a ready-made server and tests it: `atlassian`, `aws`,
+    `aws-knowledge`, `google-drive`, `grafana`, `gcp`, `github`, `playwright`, `context7`, `sentry`,
+    `postgres`, `kubernetes`, `linear` and `notion` (`lcode mcp catalog` lists them).
+  - Any other server works too, local (stdio) or remote (Streamable HTTP), configured in
+    `~/.config/lcode/mcp.json` in the standard `mcpServers` format, or per project in `.mcp.json`
+    (used only after you approve it).
+  - Browser sign-in (OAuth 2.1 with PKCE and dynamic client registration) with automatic token
+    refresh; `lcode mcp login/logout`.
+  - Speaks both the current MCP protocol (2026-07-28) and the earlier `initialize`-based versions.
+  - When the tool definitions would take more than 15% of the context window, the model finds tools
+    on demand instead (`mcp_tools` setting). `/mcp` shows servers, tools and their context cost;
+    `lcode --no-mcp` starts without them.
+
+### Fixed
+
+- `lcode bench`: stopping a run with Ctrl+C no longer leaves the running task's temporary folder
+  behind, and the summary marks the model as stopped.
+- `lcode bench` no longer lists the model it's about to benchmark as "already loaded".
+
+## [0.3.1] - 2026-09-30
+
+### Added
+
+- `lcode bench` scores models on this machine with eight small coding tasks: fixing a bug, finding
+  code, writing a script from a spec, renaming across files, a one-line edit in a long file,
+  recovering from failing commands, fixing a function to match its spec and adding a feature across
+  files. Each task runs in a temporary folder and has an automatic check, some with hidden tests.
+  It reports tasks passed, time, generation and prompt speed, tool-call errors and memory use.
+  `lcode bench model-a model-b` compares models, `--json` saves the results (a documented, versioned
+  format) and `--markdown` prints a table for a model test report.
+
 ## [0.3.0] - 2026-09-30
 
 ### Added
@@ -128,7 +165,9 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/nasser1941/lcode/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/nasser1941/lcode/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/nasser1941/lcode/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/nasser1941/lcode/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/nasser1941/lcode/compare/v0.2.0...v0.2.1

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -73,13 +73,17 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   plans multi-step tasks with a visible todo list.
 - **Long context.** 256K tokens with the default model (1M with Nemotron). You choose the window.
 - **Hardware-aware.** Detects your NVIDIA GPU or Apple Silicon Mac and picks the best model and the
-  largest context that fits: `lcode setup` does it in one step.
+  largest context that fits: `lcode setup` does it in one step. `lcode bench` compares models on
+  real coding tasks on your machine.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
   with tool calling.
+- **MCP servers, ready to go.** Connect Jira and Confluence, GitHub, AWS, Google Drive, Grafana,
+  Google Cloud, Sentry, Linear, Notion, Postgres, Kubernetes and more with one command
+  (`lcode mcp add atlassian`), or any other MCP server. Browser sign-in (OAuth) is built in.
 - **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
   search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
 - **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
@@ -125,7 +129,9 @@ lcode
 | `lcode -c` / `lcode --resume` | continue the last session here / pick a saved session from a list |
 | `lcode --model qwen3.5-9b --context 128k` | pick a model and context window for this session |
 | `lcode models` / `lcode doctor` | what fits this machine / check the installation |
+| `lcode bench qwen3.6-35b qwen3.5-9b` | compare models on small coding tasks on this machine |
 | `/undo`, `/rewind` | take back the last request's file changes, or go back further |
+| `lcode mcp catalog` / `lcode mcp add github` | ready-made MCP servers / add one |
 | `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/context`, `/compact`, `/help` | switch model, resize the context window (pick from a list), summarize, list commands |
 
@@ -170,8 +176,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [`lcode bench`: score models on your own hardware](https://github.com/nasser1941/lcode/issues/5)
-- [MCP tool servers](https://github.com/nasser1941/lcode/issues/6)
 - [Homebrew formula](https://github.com/nasser1941/lcode/issues/8) and an [optional sandbox for shell commands](https://github.com/nasser1941/lcode/issues/9)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/README.md

@@ -40,13 +40,17 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   plans multi-step tasks with a visible todo list.
 - **Long context.** 256K tokens with the default model (1M with Nemotron). You choose the window.
 - **Hardware-aware.** Detects your NVIDIA GPU or Apple Silicon Mac and picks the best model and the
-  largest context that fits: `lcode setup` does it in one step.
+  largest context that fits: `lcode setup` does it in one step. `lcode bench` compares models on
+  real coding tasks on your machine.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
   with tool calling.
+- **MCP servers, ready to go.** Connect Jira and Confluence, GitHub, AWS, Google Drive, Grafana,
+  Google Cloud, Sentry, Linear, Notion, Postgres, Kubernetes and more with one command
+  (`lcode mcp add atlassian`), or any other MCP server. Browser sign-in (OAuth) is built in.
 - **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
   search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
 - **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
@@ -92,7 +96,9 @@ lcode
 | `lcode -c` / `lcode --resume` | continue the last session here / pick a saved session from a list |
 | `lcode --model qwen3.5-9b --context 128k` | pick a model and context window for this session |
 | `lcode models` / `lcode doctor` | what fits this machine / check the installation |
+| `lcode bench qwen3.6-35b qwen3.5-9b` | compare models on small coding tasks on this machine |
 | `/undo`, `/rewind` | take back the last request's file changes, or go back further |
+| `lcode mcp catalog` / `lcode mcp add github` | ready-made MCP servers / add one |
 | `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/context`, `/compact`, `/help` | switch model, resize the context window (pick from a list), summarize, list commands |
 
@@ -137,8 +143,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [`lcode bench`: score models on your own hardware](https://github.com/nasser1941/lcode/issues/5)
-- [MCP tool servers](https://github.com/nasser1941/lcode/issues/6)
 - [Homebrew formula](https://github.com/nasser1941/lcode/issues/8) and an [optional sandbox for shell commands](https://github.com/nasser1941/lcode/issues/9)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/SECURITY.md

@@ -36,6 +36,12 @@ user, in your working directory**. It is not a sandbox. Keep in mind:
   pages are downloaded from their websites. The model writes the queries, so they can contain names or
   snippets from your code. Use `web = ask` to approve each search, or `web = off` / `--no-web` to
   keep everything local.
+- MCP servers you add run as your user (local servers) or act on your accounts (remote servers).
+  Every MCP tool call needs your approval unless you're in `yolo` mode or listed the tool under
+  `allow`. A project's `.mcp.json` is only used after you approve it, and again after it changes.
+  MCP tool results can contain prompt injections, like web pages. Tokens you enter are stored in
+  `~/.config/lcode/mcp.json` and sign-in tokens in `~/.local/state/lcode/mcp-auth/`, both readable
+  only by you.
 - Sessions (including file contents the model read) are stored in `~/.local/state/lcode/sessions`.
   Checkpoints for `/undo` keep copies of your project's files (except ignored ones) in
   `~/.local/state/lcode/checkpoints` for 14 days; turn them off with `checkpoints = false`.

lcode_cli-0.4.0/docs/bench.md

@@ -0,0 +1,172 @@
+# Benchmarking models
+
+`lcode bench` answers the most common question about local models: *which one works best for
+coding on my machine?* It runs a fixed set of small coding tasks against one or more models and
+reports how many they solved, how fast they ran and how much memory they used.
+
+```bash
+lcode bench                           # the configured model
+lcode bench qwen3.6-35b qwen3.5-9b    # compare models
+lcode bench --tasks fix-bug,rename    # run some of the tasks
+lcode bench --json results.json       # also save machine-readable results
+lcode bench --markdown                # also print a table to paste into a test report
+```
+
+```text
+lcode bench · NVIDIA GeForce RTX 4080 Laptop GPU (12 GB VRAM), 31 GB RAM · Ollama 0.32.15
+
+lcode-qwen3.6-35b · 32K context · reasoning on · 8 tasks
+  Loaded in 16s · 22.3 GB, 45% on the GPU · reads prompts at 855 tok/s
+  ✓ fix-bug       Fix a bug so the tests pass         22s  the tests pass
+  ✓ find-code     Answer with file:line                9s  next_wait at backoff.py:13
+  ✓ write-script  Write a script from a spec          13s  correct output, also on data it hadn't seen
+  ✓ rename        Rename a function across files      26s  its tests and extra checks pass
+  ✓ precise-edit  One-line edit in a long file        10s  changed only service_087's timeout
+  ✓ recover       Recover from failing commands       30s  used --source and dropped the invalid line
+  ✓ spec-fix      Fix a function to match its spec    55s  follows the whole docstring
+  ✓ feature       Add a feature across files          71s  priorities work, including old todos
+```
+
+At the end it prints a table comparing the models (see [results](#results-on-a-12-gb-laptop) below).
+
+A model usually takes 4 to 12 minutes; each task stops after 5 minutes (`--timeout`).
+
+## The tasks
+
+Every task runs in a new temporary folder, with every permission granted (`yolo` mode) and web
+access off, and ends with an automatic check. The folders are deleted afterwards unless you pass
+`--keep`, which also keeps each task's transcript (`lcode-bench.log`).
+
+| Task | The model has to | Passes when |
+|---|---|---|
+| `fix-bug` | Find and fix a bug so the failing unit tests pass | The tests pass and the test file is unchanged |
+| `find-code` | Answer a question about a small codebase | It names the right function and cites its `file:line` |
+| `write-script` | Write a script from a spec and run it | The script prints the right output, also for data it never saw |
+| `rename` | Rename a function across several files and tests | The old name is gone and extra hidden tests pass |
+| `precise-edit` | Change one value in a 900-line file of near-identical entries | Exactly that one line changed |
+| `recover` | Run a command that fails twice (a removed option, a bad input line) and work around it | The report is correct and only the bad line was dropped |
+| `spec-fix` | Fix a function from a one-line bug report so it does everything its docstring says | Hidden tests of every rule in the docstring pass, edge cases included |
+| `feature` | Add priorities to a small todo app (a new option, sorting, a marker in the output) | Its tests pass, and a scripted session gives the exact expected output, including for todos saved before the change |
+
+The first six tasks are everyday work that good models get right; the last two need careful
+reading and are where smaller models tend to slip. The checks are deterministic and can't be passed
+by hard-coding: for example, `write-script` reruns the script on new data, and `rename`, `spec-fix`
+and `feature` are checked with tests the model never saw.
+
+## What's measured
+
+| | |
+|---|---|
+| **Passed** | Tasks solved within the time limit |
+| **Time** | Total time for the tasks (loading the model is reported separately) |
+| **Generation** | Output tokens per second, across all the model's responses |
+| **Prompt reading** | Prompt tokens per second: how fast the model reads files and tool output. Measured per model with fresh 4,000-token prompts (the faster of two readings, since the first one after loading includes warm-up), because during the tasks Ollama serves most of each request from its prompt cache |
+| **Tool-call errors** | Tool calls that failed (wrong arguments, editing without reading first, unmatched edits) or that the model wrote as invalid JSON |
+| **Memory** | The model's memory use and how much of it is on the GPU, from Ollama |
+
+Results depend on the context window, so `lcode bench` uses **32K** by default on every machine,
+which makes results comparable. When comparing models, each one is unloaded before the next starts
+so every model gets the whole GPU; lcode warns if other models are already loaded. Use `--context 128k` to measure a larger window, and `--no-think`
+to measure a model without reasoning.
+
+## Results on a 12 GB laptop
+
+RTX 4080 Laptop GPU (12 GB) with 31 GB of RAM, Ollama 0.32.15, 32K context, reasoning on:
+
+| | `qwen3.6-35b` | `qwen3.5-9b` | `qwen3.5-4b` |
+|---|---|---|---|
+| fix-bug | ✓ 22s | ✓ 16s | ✓ 11s |
+| find-code | ✓ 9s | ✓ 6s | ✓ 5s |
+| write-script | ✓ 13s | ✓ 44s | ✗ 18s |
+| rename | ✓ 26s | ✓ 28s | ✓ 30s |
+| precise-edit | ✓ 10s | ✓ 12s | ✓ 8s |
+| recover | ✓ 30s | ✗ 29s | ✓ 24s |
+| spec-fix | ✓ 55s | ✓ 4m 40s | ✗ 2m 57s |
+| feature | ✓ 1m 11s | ✗ 5m 00s | ✓ 47s |
+| **Passed** | **8/8** | **6/8** | **6/8** |
+| Time | 3m 57s | 11m 55s | 5m 20s |
+| Generation | 71.4 tok/s | 60.1 tok/s | 91.3 tok/s |
+| Prompt reading | 855 tok/s | 3,507 tok/s | 5,186 tok/s |
+| Tool-call errors | 0 | 9 | 1 |
+| Memory | 22.3 GB, 45% on GPU | 6.6 GB, 100% on GPU | 4.2 GB, 100% on GPU |
+
+The small models fit entirely on the GPU and read prompts much faster, but the larger mixture-of-
+experts model solves more and needs fewer attempts. The small models' failures were real mistakes:
+copying `read_file`'s line numbers into a data file, ignoring negative numbers, missing an edge case
+of the spec, and running out of time.
+
+Models sample their answers, so a task near the edge of a model's ability can pass in one run and
+fail in the next (`qwen3.6-35b` scored 7/8 in an earlier run). Compare totals rather than single
+tasks, and run twice before drawing conclusions.
+
+## Sharing results
+
+Results from other machines, especially Apple Silicon Macs and other GPUs, decide which models lcode
+recommends. Run
+
+```bash
+lcode bench qwen3.6-35b --markdown
+```
+
+and paste the table into a
+[model test report](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml).
+
+## JSON format
+
+`--json FILE` writes one document per run. The schema is versioned: fields may be added, but
+existing fields keep their meaning until `schema` changes.
+
+```json
+{
+  "schema": 1,
+  "lcode": "0.3.1",
+  "ollama": "0.32.15",
+  "date": "2026-09-30T19:09:09+02:00",
+  "hardware": {
+    "os": "linux", "cpu": "13th Gen Intel(R) Core(TM) i9-13980HX", "ram_gib": 30.96,
+    "gpu": "NVIDIA GeForce RTX 4080 Laptop GPU", "vram_gib": 11.99, "unified": false,
+    "description": "NVIDIA GeForce RTX 4080 Laptop GPU (12 GB VRAM), 31 GB RAM"
+  },
+  "tasks": [{"id": "fix-bug", "title": "Fix a bug so the tests pass"}, …],
+  "runs": [
+    {
+      "model": "qwen3.6-35b",
+      "ollama_model": "lcode-qwen3.6-35b",
+      "context": 32768,
+      "num_batch": null,
+      "think": true,
+      "load_seconds": 16.2,
+      "prompt_tps": 854.6,
+      "memory_gb": 22.3,
+      "gpu_percent": 45,
+      "passed": 8,
+      "total": 8,
+      "seconds": 237.3,
+      "generation_tps": 71.4,
+      "tool_errors": 0,
+      "usage": {"requests": 56, "prompt_tokens": 221522, "prompt_ns": 73377987000,
+                "output_tokens": 11490, "output_ns": 161017657999},
+      "tasks": [
+        {"id": "fix-bug", "passed": true, "seconds": 21.9, "detail": "the tests pass",
+         "steps": 5, "tool_errors": 0, "error": null},
+        …
+      ],
+      "error": null,
+      "interrupted": false
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `runs[].model` | The name you gave (catalog key or Ollama tag); `ollama_model` is the model that ran |
+| `runs[].context`, `num_batch`, `think` | The settings used. lcode lowers the batch size or context if the GPU runs out of memory, and reports what it ended up using |
+| `runs[].memory_gb`, `gpu_percent` | From Ollama's `/api/ps`; `null` if unavailable |
+| `runs[].generation_tps` | Output tokens per second across the tasks; `null` if Ollama reported no timings |
+| `runs[].prompt_tps` | Prompt tokens per second for a fresh 4,000-token prompt (the faster of two readings); `null` if it couldn't be measured |
+| `runs[].usage` | Totals over the tasks as Ollama reports them. `prompt_tokens` includes tokens served from the prompt cache |
+| `runs[].tasks[].steps` | Model responses in the task |
+| `runs[].tasks[].error` | Why the task stopped early (`timed out after 300s`, an Ollama error), otherwise `null` |
+| `runs[].error` | Why the model didn't run at all (for example, not installed), otherwise `null` |
+| `runs[].interrupted` | You pressed ++ctrl+c++; the results cover the tasks that finished |

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/configuration.md

@@ -25,6 +25,7 @@ lcode config path                      # print the file location
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |
 | `searxng_url` | | Your SearXNG instance, e.g. `http://localhost:8888` |
+| `mcp_tools` | `auto` | How [MCP](mcp.md#context) tool definitions reach the model: `auto`, `direct` or `search` (on demand) |
 | `checkpoints` | `true` | Save a checkpoint before the model changes files, so [`/undo`](usage.md#undo-and-checkpoints) can restore them |
 
 Example file:
@@ -59,6 +60,9 @@ Environment variables override the file, which is useful for one-off runs and CI
 | `~/.config/lcode/config.toml` | Settings |
 | `~/.local/state/lcode/sessions/` | Saved conversations (for `lcode -c`) |
 | `~/.local/state/lcode/history` | Prompt history (++up++ in the prompt) |
+| `~/.config/lcode/mcp.json` | [MCP servers](mcp.md) (readable only by you; may contain tokens) |
+| `~/.local/state/lcode/mcp-auth/` | Sign-in tokens for remote MCP servers (readable only by you) |
+| `~/.local/state/lcode/mcp-logs/` | Error output of local MCP servers |
 | `~/.local/state/lcode/checkpoints/` | Checkpoints for `/undo` (copies of your project's files; deleted after 14 days) |
 | `~/.local/state/lcode/limits.json` | Context sizes that ran out of GPU memory on this machine (safe to delete) |
 

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/how-it-works.md

@@ -75,6 +75,8 @@ the Ollama server you configure, it only contacts the web when the model searche
 | `agent.py` | System prompt, streaming, tool loop, compaction, sessions |
 | `tools.py` | Tool schemas and implementations |
 | `permissions.py` | Approval prompts and the read-only allowlist |
+| `mcp/` | MCP client: stdio and HTTP transports, OAuth sign-in, server settings, the catalog, `lcode mcp` |
+| `bench.py` | `lcode bench`: the benchmark tasks, their checks and the reports |
 | `checkpoints.py` | Snapshots before the model changes files, for `/undo` and `/rewind` |
 | `catalog.py`, `models.toml` | Model catalog and memory estimates |
 | `hardware.py` | NVIDIA / Apple Silicon detection |

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/index.md

@@ -69,6 +69,13 @@ until the task is done, asking before it changes anything.
     Every edit is shown as a diff and every non-read-only command needs your approval, unless you
     choose otherwise. `/undo` takes back a request's file changes.
 
+-   :material-connection:{ .lg .middle } **MCP servers**
+
+    ---
+
+    Jira, GitHub, AWS, Google Drive, Grafana and more, one command each:
+    [`lcode mcp add atlassian`](mcp.md). Browser sign-in is built in.
+
 -   :material-swap-horizontal:{ .lg .middle } **Bring your own model**
 
     ---

lcode_cli-0.4.0/docs/mcp.md

@@ -0,0 +1,216 @@
+# MCP servers
+
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets lcode use tools from other
+systems: your issue tracker, GitHub, cloud accounts, databases, dashboards, a browser. Each MCP server
+adds a set of tools that the model can call, just like reading files or running commands, and every
+call is shown to you for approval first.
+
+```bash
+lcode mcp catalog          # ready-made servers
+lcode mcp add atlassian    # add one (signs you in through the browser)
+lcode mcp list             # check that your servers work
+```
+
+Then start `lcode` as usual and ask, for example, *"Summarize the open bugs assigned to me in Jira
+and find the code for the top one."*
+
+## Ready-made servers
+
+`lcode mcp add <name>` sets these up, asks for anything they need and tests the connection:
+
+| Name | What it gives the model | You need |
+|---|---|---|
+| `atlassian` | Jira, Confluence, Jira Service Management, Compass, Bitbucket | an Atlassian account (browser sign-in) |
+| `aws` | AWS CLI commands on your account, read-only unless you change it | `uvx` and AWS credentials |
+| `aws-knowledge` | Current AWS documentation, code samples, regional availability | nothing |
+| `google-drive` | Search, read and create files in Google Drive | your own Google OAuth client ([below](#google-drive)) |
+| `grafana` | Dashboards, Prometheus and Loki queries, alerts, incidents | `uvx`, a Grafana service account token |
+| `gcp` | `gcloud` commands on your Google Cloud projects | `npx` and the `gcloud` CLI, signed in |
+| `github` | Repositories, issues, pull requests, Actions | a GitHub token (or the GitHub CLI) |
+| `playwright` | A real (headless) browser: open pages, click, fill forms | `npx` |
+| `context7` | Up-to-date docs and examples for thousands of libraries | nothing (an API key is optional) |
+| `sentry` | Errors, issues, traces and releases | a Sentry account (browser sign-in) |
+| `postgres` | Schemas, read-only queries, query performance | `uvx`, a connection URL |
+| `kubernetes` | Pods, deployments, logs and events, read-only | `npx` and a kubeconfig |
+| `linear` | Issues, projects and cycles | a Linear account (browser sign-in) |
+| `notion` | Pages and databases | a Notion account (browser sign-in) |
+
+`npx` comes with [Node.js](https://nodejs.org) (18 or newer) and `uvx` with
+[uv](https://docs.astral.sh/uv/getting-started/installation/). `lcode mcp catalog` shows what's missing
+on your machine.
+
+Servers that can change things start read-only where the server supports it (`aws`, `postgres`,
+`kubernetes`); the setup note tells you which setting to change to allow writes.
+
+### Signing in
+
+Atlassian, Sentry, Linear and Notion use OAuth: lcode opens your browser, you sign in and approve
+access, and the browser hands a code back to lcode on `localhost`. lcode stores the tokens in
+`~/.local/state/lcode/mcp-auth/` (readable only by you) and refreshes them automatically.
+
+```bash
+lcode mcp login atlassian     # sign in again, e.g. after revoking access
+lcode mcp logout atlassian    # forget the tokens
+```
+
+In a session, `/mcp login <name>` does the same. On a machine without a browser, lcode prints the
+sign-in URL; open it on any computer that can reach the machine's `localhost` (for example through an
+SSH tunnel), or sign in on your own machine and copy `~/.local/state/lcode/mcp-auth/`.
+
+Atlassian organizations can also allow API tokens instead; see
+[Atlassian's guide](https://developer.atlassian.com/cloud/rovo-mcp/guides/configuring-authentication-via-api-token/)
+and add the server [by hand](#adding-your-own-servers) with an `Authorization` header.
+
+### GitHub
+
+`lcode mcp add github` offers the GitHub CLI's token if you use `gh`; otherwise create a
+[fine-grained token](https://github.com/settings/personal-access-tokens/new) with access to the
+repositories you want. Only the `repos`, `issues`, `pull_requests` and `actions` toolsets are on, to
+keep the tool list short; change `X-MCP-Toolsets` in `mcp.json` for
+[others](https://github.com/github/github-mcp-server#available-toolsets).
+
+### Google Drive
+
+Google doesn't let apps register themselves, so the Drive server needs an OAuth client from your own
+Google Cloud project:
+
+1. In a Google Cloud project, enable the **Google Drive API** and the **Google Drive MCP API**.
+2. Configure the OAuth consent screen (while it's in testing, add yourself as a test user).
+3. Create an **OAuth client ID** of type **Desktop app**, and copy its ID and secret.
+4. Run `lcode mcp add google-drive` and paste them; lcode then signs you in through the browser.
+
+See [Google's guide](https://developers.google.com/workspace/guides/configure-mcp-servers) for
+details.
+
+## Adding your own servers
+
+Any MCP server works. For a remote server, give its URL; for a local one, the command that starts it:
+
+```bash
+lcode mcp add tracker --url https://mcp.example.com/mcp
+lcode mcp add tracker --url https://mcp.example.com/mcp --header "Authorization: Bearer \${TRACKER_TOKEN}"
+lcode mcp add notes -- npx -y @modelcontextprotocol/server-filesystem /home/me/notes
+lcode mcp add db --env DATABASE_URL=postgres://localhost/app -- uvx some-postgres-mcp
+```
+
+Servers are saved in `~/.config/lcode/mcp.json` in the `mcpServers` format that most MCP servers
+document, so you can also paste a server's example config into that file:
+
+```json
+{
+  "mcpServers": {
+    "tracker": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer ${TRACKER_TOKEN}" }
+    },
+    "notes": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/notes"],
+      "tools": ["read_file", "search_files"],
+      "allow": ["read_file"]
+    }
+  }
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `command`, `args`, `env` | A local server, started by lcode and spoken to over stdin/stdout |
+| `type: "http"`, `url`, `headers` | A remote server (Streamable HTTP). Without an `Authorization` header, lcode signs in with OAuth when the server asks for it |
+| `tools` | Only offer these tools to the model (fewer tools save context and help smaller models) |
+| `allow` | Tools that run without asking; `["*"]` for all of the server's tools |
+| `timeout` | Seconds a tool call may take (default 300) |
+| `disabled` | `true` to turn the server off (`lcode mcp disable <name>`) |
+| `oauth` | For servers that need a pre-registered OAuth client: `client_id`, `client_secret`, `scopes`, `authorize_params` |
+
+Values can use environment variables: `${NAME}`, or `${NAME:-default}`. Keep tokens in environment
+variables if you prefer not to store them in the file; `mcp.json` is created readable only by you
+either way.
+
+Servers that only offer the old HTTP+SSE transport (URLs ending in `/sse`) aren't supported. Most of
+them also have a Streamable HTTP endpoint (often `/mcp`); otherwise bridge one with
+`npx -y mcp-remote <url>` as a local server.
+
+### Project servers
+
+A repository can share servers with everyone who works on it in a `.mcp.json` at its root, in the same
+format. Because those servers run programs or connect to services on your behalf, lcode asks before
+using them the first time, and again whenever the file changes.
+
+## In a session
+
+The banner lists your servers. They start in the background, and lcode waits for them (at most a
+couple of minutes, the first time `npx` or `uvx` downloads a server) before your first request.
+
+```text
+❯ /mcp
+MCP servers
+┏━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Server        ┃ Status ┃ Tools ┃ Details                                        ┃
+┡━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ aws-knowledge │ ready  │     5 │ https://knowledge-mcp.global.api.aws           │
+│ everything    │ ready  │    13 │ npx -y @modelcontextprotocol/server-everything │
+│ context7      │ ready  │     2 │ https://mcp.context7.com/mcp                   │
+└───────────────┴────────┴───────┴────────────────────────────────────────────────┘
+           Tool definitions: ~6.2K tokens · all sent with every request
+```
+
+A server that can't start shows `failed` with the reason (for example, a missing environment
+variable), and one that needs you to sign in shows `needs sign-in`; the others work normally.
+
+| Command | |
+|---|---|
+| `/mcp` | Servers, their status and the context their tools take |
+| `/mcp tools <name>` | A server's tools |
+| `/mcp login <name>` | Sign in (or again) and reconnect |
+| `/mcp restart <name>` | Restart a server, e.g. after changing its settings |
+
+Start a session without MCP servers with `lcode --no-mcp`.
+
+### Approvals
+
+Every MCP tool call shows the server, the tool and its arguments, and waits for your answer, in the
+`ask` and `auto-edit` modes alike: answer ++y++ (once), ++a++ (always, for this tool, until you quit)
+or ++n++ with an optional reason. Only `yolo` mode, or the server's `allow` list, skips the question.
+
+### Context
+
+Every tool definition is sent to the model with every request. A few servers can add tens of
+thousands of tokens, which leaves less room for your code and makes smaller models pick the wrong
+tool. So when the definitions would take more than 15% of the context window, lcode doesn't send
+them: the model sees the tool names, looks up the ones it needs with `mcp_find_tools` and calls them
+with `mcp_call`. `/mcp` and `/context` show which way is used.
+
+| `mcp_tools` setting | |
+|---|---|
+| `auto` (default) | Send the definitions if they fit in 15% of the context, otherwise on demand |
+| `direct` | Always send them |
+| `search` | Always on demand |
+
+```bash
+lcode config set mcp_tools search
+```
+
+Limiting a server's `tools` in `mcp.json` is the best fix for a crowded tool list. Some servers are
+large: Grafana offers about 80 tools and Playwright about 25, while most have a handful.
+
+## Troubleshooting
+
+- `lcode mcp list` connects to every server and shows what's wrong.
+- A local server's error output is in `~/.local/state/lcode/mcp-logs/<name>.log`.
+- **A `uvx` server fails with a Python error:** some servers don't work on the newest Python yet;
+  the ready-made ones pin Python 3.12 with `--python 3.12`, which you can add to your own. A
+  `No module named 'mcp.server.fastmcp'` error means the server needs version 1 of the MCP Python
+  SDK: add `"--with", "mcp<2"` before the package name in its `args`.
+- **"needs sign-in":** run `lcode mcp login <name>`. If the sign-in page says the redirect URL isn't
+  allowed, the service needs a pre-registered client (see [Google Drive](#google-drive)).
+- **Very slow first start:** `npx -y` and `uvx` download the server the first time.
+
+## Protocol support
+
+lcode implements MCP tools over stdio and Streamable HTTP, for both the current protocol
+(`2026-07-28`, stateless) and the earlier `initialize`-based versions (`2025-11-25` and before), and
+the MCP authorization spec (OAuth 2.1 with PKCE, protected-resource discovery, dynamic client
+registration and refresh tokens). MCP resources, prompts, sampling and elicitation aren't supported
+yet.

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/models.md

@@ -17,8 +17,8 @@ size, and it works with any other Ollama model that supports tool calling.
 | `qwen3.5-4b` | Qwen3.5 4B | dense | 3.4 GB | 256K | tested |
 
 *Tested* means the model passed lcode's two acceptance tasks end to end (see
-[test results](#test-results)). Results on other hardware are very welcome: please
-[report how a model does](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml).
+[test results](#test-results)). Results on other hardware are very welcome: run
+[`lcode bench`](bench.md) and [report how a model does](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml).
 
 Run `lcode models` to see the same list with what fits on **your** machine:
 

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.3.0 — local coding agent            │
+│ lcode v0.4.0 — local coding agent            │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.3.0 → lcode_cli-0.4.0}/docs/troubleshooting.md

@@ -62,6 +62,12 @@ of the text-only variant, run `lcode setup <key>` once to create the variant.
 - Some sites block automated downloads or need JavaScript; with `OLLAMA_API_KEY` set, lcode retries
   those through Ollama's fetch service.
 
+### An MCP server doesn't work
+
+Run `lcode mcp list`: it connects to every server and shows why one fails. A local server's error
+output is in `~/.local/state/lcode/mcp-logs/<name>.log`. Remote servers that say *needs sign-in*
+need `lcode mcp login <name>`. More in [MCP servers: Troubleshooting](mcp.md#troubleshooting).
+
 ### It's slow
 
 - The first request loads the model (10–45 s). lcode starts loading in the background as soon as it