Skip to content

✨ feat: the fragiola CLI and its MCP server (Epic #5) - #6

Merged
maurodesouza merged 5 commits into
mainfrom
feat/epic-5-mcp-server
Nov 15, 2026
Merged

maurodesouza merged 5 commits into
mainfrom
feat/epic-5-mcp-server

Conversation

@maurodesouza

Copy link
Copy Markdown
Contributor

Summary

This implements Epic #5. It adds the fragiola package: a CLI whose fragiola mcp command is an MCP server (stdio) for AI agents. It also exports the server as fragiola/mcp. The server reads fragiola.com's agent index and keeps Fragiola's two kinds of components apart in everything it says:

  • Fragiola UI is source code, added with npx shadcn@latest add @fragiola/<name>.
  • Libraries are npm packages: @fragiola/<x> plus @fragiola/<x>-react.

Closes #1
Closes #2
Closes #3
Closes #4

What changed

  • Package scaffold, CLI shell, toolchain and CI #1 Scaffold
    • The package: bin is dist/cli.mjs. The "." export has no side effects, and "./mcp" exports createServer.
    • Toolchain, pinned exact and at least 7 days old: TypeScript 7.0.2, tsdown 0.23.7, Vitest 5.1.0, Biome 2.6.6, commander 15.1.0.
    • AGENTS.md with the repository rules, and CI (check, typecheck, test, pack).
    • main was created with the first commit (LICENSE and README), because the repo was empty.
  • Agent index contract and the fragiola.com content client #2 Content
    • docs/agent-index.md (v1) is the contract fragiola/www will emit (Epic: An agent-readable fragiola.com and the MCP server page www#26). src/content/schema.ts holds its zod schemas.
    • The fetcher caches per session. Its typed ContentErrors carry a code and a suggestion. FRAGIOLA_URL overrides the base URL.
    • The catalog answers by kind, entries, pages (an ambiguous last segment is an error, never a guess), name resolution across both kinds, and fuzzy search.
  • The MCP server: fragiola mcp, instructions and tools #3 MCP server (@modelcontextprotocol/server 2.4.0, the v2 line)
    • Initialize instructions explain the two kinds.
    • Eight tools: get_fragiola_overview, list_projects, list_components, search_fragiola, get_component (with include_code), get_docs, get_api, get_install_command.
    • Output is agent-oriented Markdown. Every item is tagged [ui · source code] or [library · <package>], with the next tool or command.
  • fragiola mcp init for AI clients, and the setup docs #4 fragiola mcp init --client <claude|cursor|vscode|opencode|codex>
    • It merges into the project's config and replaces only the fragiola entry.
    • It refuses invalid JSON and prints the TOML for Codex.
    • The README covers setup, manual configuration, example prompts and troubleshooting.

Verification

  • pnpm install --frozen-lockfile, pnpm check, pnpm typecheck, pnpm test (91 tests) and pnpm build pass.
  • The tests never touch the network. A local HTTP server serves tests/fixtures/site/, which is modelled on the real ui registry and the projects' sidebars.
  • In process, a client calls every tool, including errors (site down, unsupported index version, an unknown or ambiguous name, a partial failure).
  • End to end, the built node dist/cli.mjs mcp runs over stdio with both protocol negotiations: legacy 2025-11-25, and 2026-07-28 pinned.
  • A raw stdio session with a failing tool checks that every stdout line is JSON-RPC and that logs go to stderr.
  • pnpm pack contains only dist, LICENSE, package.json and README.md.
  • An independent review found one High issue (init merged into a stale fragiola entry), four Medium and several Low. All are fixed in 9284093, with tests.

Notes

  • Decisions:
    • init prompts with Node readline (no prompt dependency), and merges JSON with a small local helper instead of deepmerge.
    • Client configs run npx fragiola@latest mcp, and fragiola is not added to the project's dependencies.
    • A UI registry name such as @fragiola/dockable can equal an npm package name, so a name with both meanings returns both.
    • The DoD's MCP Inspector check is covered by the stdio e2e test, which lists the 8 tools and reads the instructions. pnpm mcp:inspect is there for a manual look.
  • Not published. Publishing to npm and a release workflow are out of scope, by design.
  • Until Epic: An agent-readable fragiola.com and the MCP server page www#26 ships, https://fragiola.com/agents/index.json does not exist. The tools then answer NOT_FOUND with a suggestion. Use FRAGIOLA_URL to point at a local build.

Requested by: @maurodesouza

🤖 Generated with Claude Code

maurodesouza and others added 5 commits November 15, 2026 10:43
The fragiola package with its bin (dist/cli.mjs), the side-effect-free
"." export and the "./mcp" export, pinned toolchain (TypeScript 7,
tsdown, Vitest, Biome), AGENTS.md with the repository rules, and CI.

Closes #1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ient

docs/agent-index.md (v1) and its zod schemas, a cached fetcher with typed
errors (FRAGIOLA_URL overrides the base URL), and the catalog queries the
MCP tools use: projects by kind, entries, pages, name resolution across
the two kinds, and fuzzy search. Tested against a local fixture site.

Closes #2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and tools

createServer (also the fragiola/mcp export) on @modelcontextprotocol/server
v2 with initialize instructions that explain the two kinds of components,
and eight tools: get_fragiola_overview, list_projects, list_components,
search_fragiola, get_component, get_docs, get_api and get_install_command.
fragiola mcp serves it over stdio. Tested in process for every tool and
end to end over stdio with both protocol negotiations.

Closes #3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Code and Codex

Writes or merges each client's project config (npx fragiola@latest mcp)
without losing other servers, refuses invalid JSON, prints the TOML block
for Codex, and asks for the client only in a terminal. The README covers
setup, manual configuration, example prompts and troubleshooting.

Closes #4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- mcp init replaces an older fragiola entry instead of merging into it
- a failure while reading a response body is a ContentError, and every
  ContentError carries a suggestion; a failed request no longer evicts a
  newer cache entry
- a page is found by its last segment only when it is unique (AMBIGUOUS
  otherwise), never from a wrong path; API lookups prefer API pages
- get_install_command names the other kind of a shared name, get_component
  keeps the other names' results when one fails and says when docs could
  not be read, search says when the offset is past the end, unscoped
  package names resolve
- the stdout test drives a real session with a failing tool

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@maurodesouza maurodesouza added the enhancement New feature or request label Nov 15, 2026
@maurodesouza
maurodesouza merged commit c5f28f1 into main Nov 15, 2026
1 check passed
@maurodesouza
maurodesouza deleted the feat/epic-5-mcp-server branch November 15, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

1 participant