{"id":51286583,"url":"https://github.com/focus-mcp/core","last_synced_at":"2026-06-30T06:03:08.747Z","repository":{"id":351378398,"uuid":"1210469241","full_name":"focus-mcp/core","owner":"focus-mcp","description":"The runtime behind FocusMCP — Registry + EventBus + Router composing MCP bricks on demand. Browser-compatible, zero-dep, TypeScript strict.","archived":false,"fork":false,"pushed_at":"2026-05-24T20:53:00.000Z","size":671,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T12:07:47.460Z","etag":null,"topics":["ai","bricks","claude","context-engineering","event-bus","focus","library","llm","mcp","model-context-protocol","nodejs","orchestrator","registry","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://focusmcp.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/focus-mcp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"docs/GOVERNANCE.md","roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-14T12:56:05.000Z","updated_at":"2026-05-24T20:52:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/focus-mcp/core","commit_stats":null,"previous_names":["focus-mcp/core"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/focus-mcp/core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/focus-mcp","download_url":"https://codeload.github.com/focus-mcp/core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34954283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bricks","claude","context-engineering","event-bus","focus","library","llm","mcp","model-context-protocol","nodejs","orchestrator","registry","sdk","typescript"],"created_at":"2026-06-30T06:03:07.953Z","updated_at":"2026-06-30T06:03:08.739Z","avatar_url":"https://github.com/focus-mcp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2026 FocusMCP contributors\nSPDX-License-Identifier: MIT\n--\u003e\n\n# @focus-mcp/core\n\n\u003e Runtime library for FocusMCP — the MCP orchestrator that reduces token consumption by composing atomic, focused tools.\n\n[![npm version](https://img.shields.io/npm/v/@focus-mcp/core.svg)](https://www.npmjs.com/package/@focus-mcp/core)\n[![license](https://img.shields.io/npm/l/@focus-mcp/core.svg)](./LICENSE)\n[![CI](https://github.com/focus-mcp/core/actions/workflows/ci.yml/badge.svg)](https://github.com/focus-mcp/core/actions/workflows/ci.yml)\n![Built with Claude Code](https://img.shields.io/badge/built_with-Claude_Code-8A2BE2)\n\n## What is this?\n\n`@focus-mcp/core` is the library that powers [`@focus-mcp/cli`](https://github.com/focus-mcp/cli).\n\nIt 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.\n\n**Concrete example** (measured, see [benchmark](https://github.com/focus-mcp/marketplace/blob/main/benchmarks/equivalence-report.md)):\n- Reading a TS file natively: 8,522 tokens\n- Same file via `smartread.sr_summary`: 20 tokens (−99.8%)\n- Same file via `smartread.sr_signatures`: 44 tokens (−99.5%)\n\nThe savings depend on the brick: focused tools (search, refactor, audit) reduce output by 70–99%; trivial tools (echo, format) have neutral overhead.\n\n**End users should install [`@focus-mcp/cli`](https://github.com/focus-mcp/cli)**, not this package directly.\nThis package is for building custom FocusMCP hosts — servers, IDE integrations, or alternative transports.\n\n## Install\n\n```bash\nnpm install @focus-mcp/core\n```\n\n## Quick start\n\n```typescript\nimport { createFocusMcp } from '@focus-mcp/core';\nimport { defineBrick } from '@focus-mcp/sdk';\n\n// Define a brick\nconst myBrick = defineBrick({\n  manifest: {\n    name: 'my-brick',\n    version: '1.0.0',\n    description: 'Example brick',\n    tools: [{ name: 'my_tool', description: 'Does something useful' }],\n  },\n  setup({ eventBus }) {\n    return {\n      'my_tool': async ({ input }) =\u003e ({ result: `Processed: ${input}` }),\n    };\n  },\n});\n\n// Bootstrap the runtime\nconst focus = await createFocusMcp();\nawait focus.registry.register(myBrick);\n\n// Handle MCP tool calls\nconst result = await focus.router.handle('my_tool', { input: 'hello' });\n```\n\n## Architecture\n\n`@focus-mcp/core` is built on three pillars:\n\n### 1. McpRegistry — The directory\n\nKnows every brick, its manifest, its dependencies, and its runtime state. Resolves the full dependency graph (topological order, cycle detection) before startup.\n\n```typescript\nregistry.register(brick)          // register a brick + its manifest\nregistry.resolve('my-brick')      // resolve full dependency tree\nregistry.getStatus('my-brick')    // running | stopped | error | starting\nregistry.getTools()               // all tools exposed by all active bricks\n```\n\n### 2. EventBus — The nervous system\n\nBricks never call each other directly. All inter-brick communication goes through the EventBus, with built-in guards:\n\n| Guard | Protection |\n|---|---|\n| Max call depth | Prevents infinite loops (A → B → A…) |\n| Timeout | Cuts unresponsive calls after N seconds |\n| Rate limit | Throttles noisy bricks |\n| Permissions | Whitelist via `dependencies` in the manifest |\n| Payload size | Rejects oversized payloads |\n| Circuit breaker | Temporarily disables unstable bricks |\n\n```typescript\neventBus.emit('files:indexed', { path: 'src/', files: [...] })\nconst result = await eventBus.request('indexer:search', { pattern: '*.ts' })\n```\n\n### 3. McpRouter — The gateway\n\nReceives MCP calls (`tools/list`, `tools/call`) from the transport layer and dispatches them to the right brick via the EventBus.\n\n```typescript\nrouter.handle('my_tool', { input: 'hello' })\n// → Registry: \"who handles this tool?\" → brick \"my-brick\"\n// → EventBus: request(\"my-brick:my_tool\", ...)\n// → returns result\n```\n\n## Companion packages\n\n| Package | Role |\n|---|---|\n| [`@focus-mcp/core`](https://www.npmjs.com/package/@focus-mcp/core) | This package — Registry, EventBus, Router, observability |\n| [`@focus-mcp/sdk`](https://www.npmjs.com/package/@focus-mcp/sdk) | `defineBrick` helper for brick authors |\n| [`@focus-mcp/validator`](https://www.npmjs.com/package/@focus-mcp/validator) | Conformance test runner for third-party bricks |\n| [`@focus-mcp/cli`](https://github.com/focus-mcp/cli) | Primary end-user entry point — `focus add`, `focus list`, … |\n\n## Companion repositories\n\n- [`focus-mcp/cli`](https://github.com/focus-mcp/cli) — CLI MCP server (primary distribution)\n- [`focus-mcp/marketplace`](https://github.com/focus-mcp/marketplace) — Official brick catalog\n\n## Development\n\n```bash\nnvm use                  # Node 22+\npnpm install\npnpm test                # Vitest\npnpm test:coverage       # with coverage thresholds\npnpm typecheck\npnpm lint\npnpm build\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## AI-assisted development\n\nFocusMCP was built with heavy Claude Code assistance — its architecture, implementation,\ndocs, and tests have all been co-authored with AI. We embrace this openly because:\n\n1. **Transparency matters** — we'd rather disclose it than pretend otherwise\n2. **AI tooling is the context** — we're building tools for AI agents, it makes sense to use them\n3. **Quality over origin** — what matters is that the code is tested, reviewed, and working\n\n**Your AI-assisted contributions are welcome.** We don't require you to hide the fact that\nClaude, Copilot, Cursor, or any other tool helped you. What we do expect:\n\n- Tests pass, code is typed, lint is green\n- You've read the diff and understand what the PR does\n- Conventional Commits, clear PR description\n- You can explain your design choices during review\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guidelines.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-mcp%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffocus-mcp%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-mcp%2Fcore/lists"}