# Add Col MCP server and agent plugins for Claude Code and Codex · PR \#53 · screen/col

[View on GitCafe](https://git.cafe/screen/col/pull/53)

Repository: [screen/col](https://git.cafe/screen/col)

Visibility: public

State: merged

Source repository: screen/col

Source branch: feat/col-mcp-server

Target branch: main

Head commit: 3a1db14c2076669d525cd9b43ad615e786667830

[Discussion and reviews](https://git.cafe/screen/col/pull/53)

[Commits](https://git.cafe/screen/col/pull/53/commits?format=markdown)

[Files changed](https://git.cafe/screen/col/pull/53/diffs?format=markdown)

## Description

---

Implements issue #40 (spec at [spec.md](spec.md)): source-linked UI component discovery for coding agents over Col's existing catalogue, plus thin agent plugins for Claude Code and Codex.

## MCP server

- `lib/mcp-tools.ts` — the pure request-to-result tool layer: `search_libraries`, `search_components`, `get_library`, `get_component`. Each result carries stable ids, canonical source links on the library's own domain, and explicit `evidence.gaps`; compatibility facts are `supported` / `unsupported` / `unknown` and never inferred from a neighbour.
- `lib/mcp-server.ts` + `app/api/mcp/route.ts` — stateless Streamable HTTP adapter built on `@modelcontextprotocol/server`, POST-only, read-only, and never requests or stores credentials. Tools declare read-only annotations and typed zod arguments.
- `lib/corpus.ts` + `data/library-corpus/` — permission-gated documentation snapshots that refuse entries without a recorded reuse permission, fetch date, and source revision. Ships empty until permissions are recorded.
- `lib/compatibility.ts` + `data/compatibility.ts` — explicit three-state compatibility facts, seeded for `ant-design` and `chakra-ui`; every recorded fact cites an official source.

## Search quality harness

- `lib/mcp-eval.test.mjs` — fixture set of realistic agent queries mapped to expected hits, run in the existing test runner. Gates alias resolution, stack constraints, honest empty results, and explicit unknowns before anyone reaches for embeddings.
- `lib/mcp-tools.test.mjs`, `lib/corpus.test.mjs`, `lib/compatibility.test.mjs` — behavior tests for the tool envelopes, pagination caps, schema errors, and the corpus/compatibility validators.

## Agent plugins

One shared package (`plugin/`) serves both hosts: a shared `skills/ui-components/SKILL.md` workflow skill and one `.mcp.json` connection manifest, with a thin host manifest each — `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`. Install paths:

- Claude Code: `claude plugin marketplace add screen-gd/Col` → `claude plugin install col@col` (marketplace catalog at `.claude-plugin/marketplace.json`), or `claude --plugin-dir plugin`.
- Codex: `codex plugin marketplace add screen-gd/Col` → `codex plugin add col@col` (marketplace catalog at `.agents/plugins/marketplace.json`).

`plugin/README.md` documents install and connection verification for both.

## Notes

- The bulk rewrite in `data/library-details/index.ts` is mechanical: import specifiers gain explicit `.ts` extensions so the Node test suites can import the module graph directly. No data changed.
- `lib/directory.ts` exports `componentRank` for reuse by the tool layer; no behavior change.

## Verification

- `npx tsc --noEmit` clean; `npm test` 67/67 green (build + full suite).
- Endpoint proven over real HTTP: SDK client session against `npm start` completed initialize → `tools/list` (all four tools) → three `tools/call` → clean close.
- Both plugin install flows validated with the real CLIs (codex-cli 0.153.4, claude CLI) in isolated configs: marketplaces register, `col@col` installs, the MCP connection resolves to the production URL.
- The production URL `https://collection-of-libs.vercel.app/api/mcp` goes live when this deploys; until then the plugins point at an endpoint that is not yet up.

<!-- capy-badge:start -->
<a href="https://capy.ai/thread/jam_01M4351C0NSVFF63HFD74CV96C"><picture><source media="(prefers-color-scheme: dark)" srcset="https://capy.ai/badge/accent-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://capy.ai/badge/accent-light.svg"><img alt="Open in Capy" src="https://capy.ai/badge/accent-light.svg"></picture></a>
<!-- capy-badge:end -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added a read-only catalogue assistant for Claude Code and Codex, with tools to search UI libraries and components or retrieve their details.
  * Results include source links, compatibility information, and verification status with any known coverage gaps.
  * Added a hosted connection option for the assistant and setup guidance for connecting from supported hosts.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->