@focus-mcp/core

Runtime library for FocusMCP — the MCP orchestrator that reduces token consumption by composing atomic, focused tools.

What is this?

@focus-mcp/core is the library that powers @focus-mcp/cli.

It provides the Registry, EventBus, Router, SDK, Validator, and marketplace resolver — the three pillars that let atomic MCP bricks communicate, compose, and serve AI agents with minimal context overhead.

Concrete example (measured, see benchmark):

• Reading a TS file natively: 8,522 tokens
• Same file via smartread.sr_summary: 20 tokens (−99.8%)
• Same file via smartread.sr_signatures: 44 tokens (−99.5%)

The savings depend on the brick: focused tools (search, refactor, audit) reduce output by 70–99%; trivial tools (echo, format) have neutral overhead.

End users should install @focus-mcp/cli, not this package directly. This package is for building custom FocusMCP hosts — servers, IDE integrations, or alternative transports.

Install

npm install @focus-mcp/core

Quick start

import { createFocusMcp } from '@focus-mcp/core';
import { defineBrick } from '@focus-mcp/sdk';

// Define a brick
const myBrick = defineBrick({
  manifest: {
    name: 'my-brick',
    version: '1.0.0',
    description: 'Example brick',
    tools: [{ name: 'my_tool', description: 'Does something useful' }],
  },
  setup({ eventBus }) {
    return {
      'my_tool': async ({ input }) => ({ result: `Processed: ${input}` }),
    };
  },
});

// Bootstrap the runtime
const focus = await createFocusMcp();
await focus.registry.register(myBrick);

// Handle MCP tool calls
const result = await focus.router.handle('my_tool', { input: 'hello' });

Architecture

@focus-mcp/core is built on three pillars:

1. McpRegistry — The directory

Knows every brick, its manifest, its dependencies, and its runtime state. Resolves the full dependency graph (topological order, cycle detection) before startup.

registry.register(brick)          // register a brick + its manifest
registry.resolve('my-brick')      // resolve full dependency tree
registry.getStatus('my-brick')    // running | stopped | error | starting
registry.getTools()               // all tools exposed by all active bricks

2. EventBus — The nervous system

Bricks never call each other directly. All inter-brick communication goes through the EventBus, with built-in guards:

Guard	Protection
Max call depth	Prevents infinite loops (A → B → A…)
Timeout	Cuts unresponsive calls after N seconds
Rate limit	Throttles noisy bricks
Permissions	Whitelist via dependencies in the manifest
Payload size	Rejects oversized payloads
Circuit breaker	Temporarily disables unstable bricks

eventBus.emit('files:indexed', { path: 'src/', files: [...] })
const result = await eventBus.request('indexer:search', { pattern: '*.ts' })

3. McpRouter — The gateway

Receives MCP calls (tools/list, tools/call) from the transport layer and dispatches them to the right brick via the EventBus.

router.handle('my_tool', { input: 'hello' })
// → Registry: "who handles this tool?" → brick "my-brick"
// → EventBus: request("my-brick:my_tool", ...)
// → returns result

Companion packages

Package	Role
@focus-mcp/core	This package — Registry, EventBus, Router, observability
@focus-mcp/sdk	defineBrick helper for brick authors
@focus-mcp/validator	Conformance test runner for third-party bricks
@focus-mcp/cli	Primary end-user entry point — focus add, focus list, …

Companion repositories

• focus-mcp/cli — CLI MCP server (primary distribution)
• focus-mcp/marketplace — Official brick catalog

Development

nvm use                  # Node 22+
pnpm install
pnpm test                # Vitest
pnpm test:coverage       # with coverage thresholds
pnpm typecheck
pnpm lint
pnpm build

Contributing

See CONTRIBUTING.md.

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