@focus-mcp/cli

Focus your AI agents on what matters. Measured savings: 65.9% on output tokens across 29 bricks (details).

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

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

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:

{
    "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:

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

Commands

| Command | Description | |---|---| | focus list | List installed bricks (reads ~/.focus/center.json) | | focus info <name> | Show details for a brick (version, catalog, config) | | focus start | Launch FocusMCP as an MCP server over stdio | | focus add <name> | Install a brick from the catalog | | focus remove <name> | Uninstall a brick | | focus search <query> | 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

# 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:

{
    "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=<patterns> to mark tools as always-loaded (surfaced as _meta.anthropic/alwaysLoad: true in MCP responses):

focus start --pin="ts_index,sym_find"

Manage from the terminal: focus tools:

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.

Links

• Marketplace: https://github.com/focus-mcp/marketplace
• Core library: https://github.com/focus-mcp/core
• Official catalog: https://raw.githubusercontent.com/focus-mcp/marketplace/main/publish/catalog.json
• Website: https://focusmcp.dev

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 for the full guidelines.

License

MIT