Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/focus-mcp/cli

Focus your AI agents on what matters. 68+ bricks, 1 MCP server, modular context — from 200k to 2k tokens. Works with Claude Code, Cursor, Codex.
https://github.com/focus-mcp/cli

agent-tools ai bricks claude claude-code cli codex context-engineering cursor focus ink llm marketplace mcp model-context-protocol nodejs orchestrator tools tui typescript

Last synced: about 9 hours ago
JSON representation

Focus your AI agents on what matters. 68+ bricks, 1 MCP server, modular context — from 200k to 2k tokens. Works with Claude Code, Cursor, Codex.

Awesome Lists containing this project

README 

          



# @focus-mcp/cli



> Focus your AI agents on what matters. **Measured savings: 65.3% on output tokens** across all 69 bricks ([details](https://github.com/focus-mcp/marketplace/blob/main/benchmarks/equivalence-report.md)).



[![npm](https://img.shields.io/npm/v/@focus-mcp/cli)](https://www.npmjs.com/package/@focus-mcp/cli)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

[![CI](https://github.com/focus-mcp/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/focus-mcp/cli/actions/workflows/ci.yml)

![Built with Claude Code](https://img.shields.io/badge/built_with-Claude_Code-8A2BE2)



## What



FocusMCP is an MCP (Model Context Protocol) orchestrator. Instead of giving your AI agent ALL your tools at once — polluting its context window — you compose **bricks**: atomic MCP modules that load on demand.



- **68+ official bricks** covering files, code intel, git, shell, reasoning, search, and more

- **One CLI, one MCP server**, modular capabilities

- Works with **Claude Code, Cursor, Codex, Gemini CLI**, any MCP-compatible AI



## Install



```bash

npm install -g @focus-mcp/cli

```



Or via the **Claude Code native plugin**:



### Install for Claude Code



**Option 1 — Two lines (works today)**

```

/plugin marketplace add focus-mcp/cli

/plugin install focus-mcp@focus-mcp-cli

```



**Option 2 — Manual MCP add**

```bash

claude mcp add focus-mcp npx @focus-mcp/cli start

```



*(Official single-liner `/plugin install focus-mcp@claude-plugins-official` coming once Anthropic accepts the submission.)*



Requires **Node.js ≥ 22**.



## Quick start



Add FocusMCP as an MCP server in your AI client config:



```json

{

    "mcpServers": {

        "focus": {

            "command": "npx",

            "args": ["-y", "@focus-mcp/cli", "start"]

        }

    }

}

```



For **Claude Code** specifically, this is already wired via the native plugin above.



Then browse and manage bricks:



```bash

focus browse          # Interactive TUI — browse, search, install/uninstall bricks

focus search git      # Search the catalog for bricks matching "git"

focus add echo        # Install the "echo" brick

focus list            # Show all installed bricks

focus info echo       # Show details for a specific brick

```



## Windows



FocusMCP supports Windows as of `@focus-mcp/cli >= 2.3.1`. Earlier versions may fail when installing or loading bricks because of Windows `.cmd` wrappers and path separator handling.



### Requirements



- Windows 10/11

- Node.js >= 22

- npm available from PowerShell or Command Prompt

- `@focus-mcp/cli >= 2.3.1`



### Install



```powershell

npm install -g @focus-mcp/cli@latest

focus --version

```



Expected:



```

@focus-mcp/cli 2.3.1 or newer

```



### Test



```powershell

focus search cache

focus add cache

focus list

```



### MCP client config on Windows



For Windows MCP clients, prefer launching through `cmd.exe` and the `.cmd` shim, especially when using nvm4w or when the client does not inherit your interactive shell PATH.



Generic MCP JSON:



```json

{

    "mcpServers": {

        "focus": {

            "command": "C:\\\\Windows\\\\System32\\\\cmd.exe",

            "args": ["/d", "/c", "focus.cmd", "start"]

        }

    }

}

```



If your MCP client cannot find `focus.cmd`, use the full path:



```json

{

    "mcpServers": {

        "focus": {

            "command": "C:\\\\Windows\\\\System32\\\\cmd.exe",

            "args": ["/d", "/c", "C:\\\\nvm4w\\\\nodejs\\\\focus.cmd", "start"],

            "env": {

                "PATH": "C:\\\\nvm4w\\\\nodejs;C:\\\\Users\\\\\\\\AppData\\\\Roaming\\\\npm;C:\\\\Windows\\\\System32;C:\\\\Windows"

            }

        }

    }

}

```



### Codex on Windows



Add this to `%USERPROFILE%\.codex\config.toml`:



```toml

[mcp_servers.focus]

command = "C:\\\\Windows\\\\System32\\\\cmd.exe"

args = ["/d", "/c", "C:\\\\nvm4w\\\\nodejs\\\\focus.cmd", "start"]

startup_timeout_sec = 30

tool_timeout_sec = 120



[mcp_servers.focus.env]

PATH = "C:\\\\nvm4w\\\\nodejs;C:\\\\Users\\\\\\\\AppData\\\\Roaming\\\\npm;C:\\\\Windows\\\\System32;C:\\\\Windows"

FOCUS_NO_UPDATE_NOTIFY = "1"

```



Replace `` and the Node path if you do not use nvm4w.



### Troubleshooting



If brick installation fails with:



```

spawn npm ENOENT

```



update FocusMCP:



```powershell

npm install -g @focus-mcp/cli@latest

```



If brick loading fails with:



```

escapes bricksDir

```



make sure `focus --version` reports `2.3.1` or newer.



## Commands



| Command | Description |

|---|---|

| `focus list` | List installed bricks (reads `~/.focus/center.json`) |

| `focus info ` | Show details for a brick (version, catalog, config) |

| `focus start` | Launch FocusMCP as an MCP server over stdio |

| `focus add ` | Install a brick from the catalog |

| `focus remove ` | Uninstall a brick |

| `focus search ` | Search the catalog |

| `focus catalog` | Show and manage catalog sources |

| `focus browse` | Interactive TUI browser (see below) |



## Interactive TUI — `focus browse`



`focus browse` opens a full-screen terminal interface to explore, search, and manage bricks without leaving your terminal.



```

┌─ Bricks (68) ────────────────┬─ echo ───────────────────────────────────┐

│ > echo              ✓        │                                          │

│   indexer                    │  A simple echo brick for testing.        │

│   shell                      │                                          │

│   git-log                    │  Version   ^1.0.0                        │

│   web-search                 │  Source    @focus-mcp/echo               │

│   …                          │  Status    installed                     │

│                              │                                          │

│  / search  i install         │  [i] Install   [u] Uninstall             │

│  ↑↓ nav    Enter open        │  [?] Help                                │

└──────────────────────────────┴──────────────────────────────────────────┘

```



**Keybindings:**



| Key | Action |

|---|---|

| `↑` / `↓` | Navigate the brick list |

| `Enter` | Open brick details |

| `/` | Search / filter |

| `i` | Install selected brick |

| `u` | Uninstall selected brick |

| `?` | Toggle help overlay |

| `q` / `Esc` | Quit |



## Filtering exposed tools



By default, `focus start` exposes all tools from every loaded brick plus the focus management

tools (`focus_*`). You can hide specific tools using a blacklist.



### Per-launch: `--hide`



```bash

# Hide a single tool

focus start --hide=sym_get



# Hide an entire family with a glob

focus start --hide="focus_*"



# Hide multiple patterns (comma-separated)

focus start --hide="sym_get,ts_cleanup"

```



Patterns support a trailing `*` glob (`focus_*` matches `focus_install`, `focus_list`, etc.).

Exact names are also accepted.



> **Note:** `focus_tools` is always visible regardless of the hidden list, so you can always

> manage tool visibility from within your AI client.



### Persistent config: `~/.focus/config.json`



Add a `tools` section to persist filters across sessions:



```json

{

    "tools": {

        "hidden": ["sym_get", "fo_delete"],

        "alwaysLoad": ["ts_index"]

    }

}

```



CLI flags override the config file. If neither is set, all tools are exposed (default).



Add `--pin=` to mark tools as always-loaded (surfaced as `_meta.anthropic/alwaysLoad: true` in MCP responses):



```bash

focus start --pin="ts_index,sym_find"

```



### Manage from the terminal: `focus tools:`



```bash

focus tools:list               # show current hidden + alwaysLoad lists

focus tools:hide sym_get       # add sym_get to the hidden list

focus tools:hide "focus_*"     # hide an entire family (glob)

focus tools:show sym_get       # remove sym_get from the hidden list

focus tools:pin ts_index       # mark ts_index as alwaysLoad

focus tools:unpin ts_index     # remove ts_index from alwaysLoad

focus tools:clear              # reset both lists



# Legacy aliases (permanent, no deprecation):

focus filter list

focus filter hide sym_get

```



Changes are written to `~/.focus/config.json` and take effect on the next `focus start`.



### From your AI client: `focus_tools` MCP tool



The `focus_tools` MCP tool lets your AI agent manage tool visibility directly:



```

focus_tools action=hide   pattern=sym_get

focus_tools action=show   pattern=sym_get

focus_tools action=pin    pattern=ts_index

focus_tools action=unpin  pattern=ts_index

focus_tools action=list

focus_tools action=clear

```



Restart `focus start` (or reload your MCP client) to apply changes.



## Architecture



```

AI client (Claude Code, Cursor, Codex, …)

       │ stdio (JSON-RPC / MCP)

       ▼

@focus-mcp/cli  (this package)

  ├─ @modelcontextprotocol/sdk  StdioServerTransport

  ├─ @focus-mcp/core            Registry + EventBus + Router + brick loader

  └─ ~/.focus/center.json       user brick declarations

```



**Bricks** are atomic MCP modules. Each brick exposes exactly one domain of tools to the AI agent. You declare which bricks you want in `~/.focus/center.json`; FocusMCP loads them on demand when `focus start` is called.



**Why not give the agent all tools at once?** Because a 200k-token context window filled with hundreds of tool descriptions leaves very little room for actual work. FocusMCP keeps the agent's context lean — ~2k tokens for the orchestrator itself — and loads domain-specific tools only when needed.



## For AI agents



If you are an AI agent (Claude Code, Cursor, Cline, Codex, etc.) and want to bootstrap on a new project using FocusMCP, read the **[Agent Bootstrap Guide](./docs/AGENT_GUIDE.md)**. It covers stack detection, brick search and install, tool pinning, and common workflows — optimized for LLM consumption.



## Links



- **Marketplace**: 

- **Core library**: 

- **Official catalog**: 

- **Website**: 



## AI-assisted development



FocusMCP was built with heavy Claude Code assistance — its architecture, implementation,

docs, and tests have all been co-authored with AI. We embrace this openly because:



1. **Transparency matters** — we'd rather disclose it than pretend otherwise

2. **AI tooling is the context** — we're building tools for AI agents, it makes sense to use them

3. **Quality over origin** — what matters is that the code is tested, reviewed, and working



**Your AI-assisted contributions are welcome.** We don't require you to hide the fact that

Claude, Copilot, Cursor, or any other tool helped you. What we do expect:



- Tests pass, code is typed, lint is green

- You've read the diff and understand what the PR does

- Conventional Commits, clear PR description

- You can explain your design choices during review



See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guidelines.



## License



[MIT](./LICENSE)