Skip to Content
drksci
System

MCP tools

Tools the site serves to agents over MCP at /mcp, with the input each takes and when to call it.

The site serves an MCP endpoint at /mcp over Streamable HTTP, as server drksci-site. Every tool reads; none writes, and there is no authentication. Each tool wraps a plain function in src/mcp/core, which scripts and tests call directly.

Server instructions

The drksci site's design system, writing guide and content, for an agent writing or maintaining pieces.

Every tool reads; none writes. Publishing is done in a checkout of the repository: edit files under content/pieces/<slug>/, run bun run check, and open a pull request. There is no publish tool and no authentication in this version.

Everything in the system describes itself in one catalog: blocks, layouts, templates, token groups, figure primitives, writing elements, audit rules, résumé commands and scripts. catalog_list browses or searches it, catalog_get returns one full spec (use, avoid, inputs, what each size shows, how text is shortened, an example). Blocks take size compact, normal or expanded, and text that can be long takes a short form beside its full one.

Writing or editing a piece: catalog_list with kind "block" and "layout" for what a section can hold, catalog_get for the block about to be used, get_writing_guide for the rules of the element being written, then validate_draft on the MDX before committing it. list_layouts, list_blocks and get_writing_guide's index are superseded by the catalog and kept for now. Adding a component or block: call find_similar first and reuse or extend what it returns; it searches the catalog as well as the source. Housekeeping: audit lists what has drifted from the system, with a fix for each finding. propose_consolidation turns the findings into a ranked plan (it changes nothing); carry the plan out in a checkout and open a pull request.

Tools

get_tokens

Design tokens of a theme: custom property name, light and dark value, tier (primitive, semantic, component) and group. Call before writing any CSS or figure styling; a piece uses these and never a raw colour, size or spacing value.

InputTypeMeaning
themestringoptionalTheme name; omit for the default. The result lists every theme.
tierprimitive, semantic, componentoptionalReturn one tier only. Component CSS reads the component tier.

get_design_sheet

One Markdown summary of the design system, generated from the tokens, plot kit, layout registry, writing guide and structure rules: principles, colour, pens, type, space, figures, layout and the writing rules. Set full to also get every shared stylesheet, the writing guide, the catalog and the manuals, about 350 kB. The same text is served at /tokens.md and /tokens/full.md.

InputTypeMeaning
themestringoptionalTheme name; omit for drksci.
fullbooleanoptionalReturn the full dump.

catalog_list

The catalog of every unit of the system, one line each: id, kind and summary. Kinds: block, layout, template, token (a token group), figure (a plot primitive), element (a writing-guide element), rule (an audit rule), command (a résumé command), script. Filter by kind, search by words, or both. Call first when looking for something to use; then call catalog_get on the id.

InputTypeMeaning
kindblock, layout, template, token, figure, element, rule, command, scriptoptionalReturn one kind only, such as block.
querystringoptionalWords that must all appear in the id, summary, use or avoid text.

catalog_get

The full spec of one unit: summary, when to use it, when not to, typed inputs, what compact, normal and expanded each show, how each text field is shortened (clamp, drop, abbreviate or require), minimum width and an example. Give an id from catalog_list, as kind:name (block:Figure) or a bare name when only one unit has it. Call before using a block, layout or template.

InputTypeMeaning
idstringrequiredId from catalog_list, such as "block:Stat" or "Stat".

list_layouts

Superseded by catalog_list with kind "layout". Layouts a Section can take (opener, column, spread, plate and others), with what content selects each one and how it collapses on a narrow screen. A Section picks its layout from the blocks it contains; call this to learn which blocks to put together for the layout wanted.

Takes no input.

list_blocks

Superseded by catalog_list with kind "block". Shared block components usable in any piece's MDX without an import (Prose, Figure, Stat and others), with the kind each declares and its minimum useful width. Call before writing a section, and before proposing a new component.

Takes no input.

get_writing_guide

House writing rules; the elements are also in the catalog (kind element). Without an element: the voice principles, the lint rules and an index of element ids (title, deck, lede, caption, alt-text and others). With an element id: that element's purpose, length limits, voice, what to do and avoid, and a good and a bad example. Call with the element being written before drafting it.

InputTypeMeaning
elementstringoptionalElement id, such as "title" or "caption". Omit for the index.

validate_draft

Checks an MDX draft the way CI will: frontmatter against the schema for its kind, MDX syntax, and the prose lint for every element (lengths, first person, stock vocabulary, leading labels, alt text). Returns findings with severity, line and the writing-guide element each concerns. Nothing is saved. Call on the full file text before committing; an error would fail bun run check.

InputTypeMeaning
mdxstringrequiredThe whole MDX file, frontmatter included.
kindpiece, docdefault piece"piece" for content/pieces/<slug>/index.mdx, "doc" for a page under content/docs.

list_pieces

Every published piece and every part of an anthology (slug/part): slug, path of its index.mdx, title, description and date. Call to find a slug for get_piece, or to check whether a subject already has a piece.

Takes no input.

get_piece

One piece by slug: frontmatter, the MDX source and the files in its folder. Call before editing a piece, or to see how an existing piece uses the layout kit.

InputTypeMeaning
slugstringrequiredSlug from list_pieces; a part of an anthology is slug/part.

audit

Housekeeping audit of the deployed tree: raw colour and size literals, unused tokens and components, near-duplicate components, orphaned assets, pieces crossing their folder boundary, stale generated files, structure and naming conventions, and budgets. Each finding has a rule id, severity, location and fix. Call before a clean-up, or after a change to see what it left behind. Reflects the deployed commit, not a local checkout: run bun run audit there.

InputTypeMeaning
severityerror, warn, infooptionalLowest severity returned; "error" is what fails CI. Omit for all.
rulestringoptionalReturn one rule only, such as "near-duplicate".

propose_consolidation

A ranked plan to shrink the repository, built from the audit: near-duplicate components to merge, unused blocks, components and tokens to remove, orphaned assets to delete, pieces that override shared styles, and budgets nearly spent. Each item says what to merge or remove, the files, the lines, tokens or files it saves, and the risk with what to check. It writes nothing and opens nothing: this endpoint has no authentication and no repository access. Make the change in a checkout, one item per pull request, run bun run check, then open the pull request. Reflects the deployed commit.

InputTypeMeaning
limitintegeroptionalItems to return, highest rank first; default 15.
rulestringoptionalOnly items for one audit rule, such as "near-duplicate".

find_similar

Looks for an existing catalog unit, block kind, layout or component, shared or bespoke to a piece, that resembles a proposed one. Give any of a name, a one-line description, or draft source. Returns matches with a score from 0 to 1 and the reason. Call before creating a component; reuse or extend a match scoring 0.5 or more.

InputTypeMeaning
namestringoptionalProposed component name, such as "StatCard".
descriptionstringoptionalWhat it shows or does, in a sentence.
sourcestringoptionalDraft TSX source of the component.

On this page