feat(webfont-mcp): add MCP server, was tools, and public exports by jimmyandrade · Pull Request #796 · itgalaxy/webfont

jimmyandrade · 2026-07-07T21:25:31Z

Summary

Proposed changes

Add private packages/webfont-mcp workspace (stdio MCP server, path sandbox, tools: convert_svgs_to_font, diagnose_svgs, list_webfont_options, validate_was_config, convert_from_was; not published; tests via npm test -w webfont-mcp).
Expose programmatic option metadata from the webfont entry: buildWebfontOptionsReference(), buildCliFlagReferences(), defaultWebfontOptions(), CLI_FLAG_SECTIONS, and related types.
Export headless .was helpers from webfont(): parseWasConfigJson, guardLoadedWasConfigs, loadWasConfigs, mapWasConfigToWebfontOptions, buildWasConfigFromWizard, basename cleaners, and WebfontAssistantWasConfig types.
Move headless .was modules from cli/assistant/ to src/was/ so they ship in the library build; CLI assistant imports from there.
Move cliFlagCatalog.ts to src/optionsReference/ (single source for CLI help and the new API); keep a thin re-export shim under cli/meow/; include --assistant / --assistant-config flags from feat(cli): add interactive assistant and webfont-assistant .was support #797.
Document the programmatic reference in docs/configuration.md; regenerate docs/cli.md.

Related issue

#720

Dependencies added/removed (if applicable)

Add (webfont-mcp): @modelcontextprotocol/sdk, globby, zod; webfont via file:../webfont.

Testing

I have added or updated tests that prove my fix is effective or that my feature works (if applicable)
- Unit test

How to test

npm test -w webfont — includes optionsReference, was/, index export, and assistant CLI tests.
npm run build -w webfont && npm test -w webfont-mcp — MCP unit/integration tests (13 tests).
Optional: npm run build -w webfont-mcp && node packages/webfont-mcp/dist/main.js and wire in Cursor per packages/webfont-mcp/README.md.

Test configuration

N/A

Checklist

I have added corresponding labels to this PR (like bug, enhancement...);
My commits follow the Conventional Commits 1.0 Guidelines;
My code follows the style guidelines of this project;
I have performed a self-review of my own code;
I have mapped technical debts found on my changes;
I have made changes to the documentation (if applicable);
My changes generate no new warnings or errors;

Copilot

Pull request overview

Adds a new internal MCP server workspace (packages/webfont-mcp) that exposes the existing SVG→webfont pipeline as structured MCP tools, and introduces a public “options reference” API from the webfont package so tooling can query defaults + CLI flag metadata programmatically.

Changes:

Introduce packages/webfont-mcp (private workspace) implementing stdio MCP tools: conversion, SVG diagnostics, and option listing.
Add optionsReference/ to webfont and export option metadata builders/types from packages/webfont/src/index.ts.
Move the CLI flag catalog to src/optionsReference/ as the single source for CLI docs + the new reference API, updating docs accordingly.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/webfont/src/optionsReference/formatCliFlagDescription.ts	Helper to normalize multi-line CLI flag descriptions into a single string.
packages/webfont/src/optionsReference/cliFlagCatalog.ts	New canonical CLI flag catalog and help content sections for reuse by CLI/docs/tooling.
packages/webfont/src/optionsReference/buildWebfontOptionsReference.ts	Builds a structured options reference (defaults + CLI flags + API-only docs).
packages/webfont/src/optionsReference/buildWebfontOptionsReference.test.ts	Tests to ensure the exported options reference matches runtime defaults/catalog.
packages/webfont/src/optionsReference/apiOnlyOptionsCatalog.ts	Catalog of programmatic-only options not represented in CLI flags.
packages/webfont/src/index.ts	Exports the new options reference API and `defaultWebfontOptions` (plus `WebfontOptions` type).
packages/webfont/src/index.test.ts	Verifies new exports are present on the public entry point.
packages/webfont/src/cli/meow/renderCliHelp.ts	Updates the “source of truth” path for generated CLI docs.
packages/webfont/src/cli/meow/cliFlagCatalog.ts	Thin re-export shim to keep internal imports stable after moving the catalog.
packages/webfont/docs/configuration.md	Documents the new programmatic options reference (`buildWebfontOptionsReference`).
packages/webfont/docs/cli.md	Updates the generated-doc maintainer note to point at the moved catalog.
packages/webfont-mcp/vitest.config.ts	Vitest config for the new MCP workspace tests.
packages/webfont-mcp/tsconfig.json	TypeScript build configuration for the MCP workspace.
packages/webfont-mcp/src/serializeResult.ts	Serializes conversion outputs (written files + metadata) for MCP responses.
packages/webfont-mcp/src/resolveSvgInputs.ts	Resolves glob patterns to sandboxed SVG input paths.
packages/webfont-mcp/src/pathSandbox.ts	Implements workspace-root path sandboxing for MCP file operations.
packages/webfont-mcp/src/pathSandbox.test.ts	Tests for sandbox path resolution constraints.
packages/webfont-mcp/src/main.ts	CLI entry for starting the stdio MCP server.
packages/webfont-mcp/src/listWebfontOptionsContent.ts	Produces a JSON options reference including MCP-specific tool notes.
packages/webfont-mcp/src/listWebfontOptionsContent.test.ts	Tests for MCP options reference content.
packages/webfont-mcp/src/diagnoseSvgs.ts	Implements SVG diagnostics tool using `diagnoseSvgContents`.
packages/webfont-mcp/src/diagnoseSvgs.test.ts	Tests diagnostic results against repo fixtures.
packages/webfont-mcp/src/createServer.ts	Registers MCP tools and schemas on an `McpServer`.
packages/webfont-mcp/src/convertSvgsToFont.ts	Implements conversion tool using `webfont()` + `writeResultFiles()` within sandbox.
packages/webfont-mcp/src/convertSvgsToFont.test.ts	Integration-style test for producing a `.woff2` output under sandbox.
packages/webfont-mcp/README.md	Usage/setup docs for running the MCP server and configuring Cursor.
packages/webfont-mcp/package.json	Declares private workspace metadata, deps, scripts, and bin entry.
packages/webfont-mcp/.gitignore	Ignores build artifacts and temp dirs for the MCP workspace.
package-lock.json	Lockfile updates for newly added MCP dependencies/workspace.

Expose buildWebfontOptionsReference(), defaultWebfontOptions(), and CLI_FLAG_SECTIONS from the webfont entry so agents can reuse cliFlagCatalog metadata. Add private webfont-mcp package (stdio tools, path sandbox, local tests only). Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Move headless .was helpers to src/was/ for library build, export them from webfont(), and add validate_was_config / convert_from_was MCP tools that reuse the same mapping as --assistant-config. Co-authored-by: Cursor <cursoragent@cursor.com>

Drop duplicate snapshot 2 left from an accidental update; the async glyphTransformFn test only asserts one template snapshot. Co-authored-by: Cursor <cursoragent@cursor.com>

Ship .cursor/mcp.json with ${workspaceFolder} so contributors can enable the local webfont MCP without machine-specific absolute paths. Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

Copilot reviewed 41 out of 50 changed files in this pull request and generated 1 comment.

Presence (`!== undefined`) is not truthiness — empty exclusive MCP inputs must fail with a field error instead of falling through to JSON.parse. Codify the pattern in AGENTS.md (Copilot review on #796). Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

Copilot reviewed 42 out of 51 changed files in this pull request and generated 3 comments.

+import { PathSandboxError } from "./pathSandbox.js";
+import { validateWasConfig } from "./validateWasConfig.js";
+
+const formatSchema = z.enum(["eot", "otf", "woff", "woff2", "svg", "ttf"]);


+import { resolveSvgInputPaths } from "./resolveSvgInputs.js";
+import { serializeConversionResult } from "./serializeResult.js";
+
+export type WebfontFormat = "eot" | "otf" | "woff" | "woff2" | "svg" | "ttf";


+const convertWasEntry = async (
+  entry: Awaited<ReturnType<typeof validateWasConfig>>["entries"][number],
+): Promise<SerializedConversionResult> => {
+  const result = await webfont(entry.mappedOptions);
+  const dest = entry.mappedOptions.dest;


jimmyandrade requested a review from Copilot July 7, 2026 22:14

jimmyandrade self-assigned this Jul 7, 2026

jimmyandrade added the enhancement label Jul 7, 2026

Copilot started reviewing on behalf of jimmyandrade July 7, 2026 22:14 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread packages/webfont/src/optionsReference/cliFlagCatalog.ts Outdated

Comment thread packages/webfont/src/optionsReference/cliFlagCatalog.ts Outdated

Comment thread packages/webfont-mcp/src/pathSandbox.ts

Comment thread packages/webfont/src/optionsReference/cliFlagCatalog.ts Outdated

jimmyandrade and others added 4 commits July 10, 2026 09:06

fix(webfont): satisfy knip for CLI catalog shim re-export

dec8ffe

Co-authored-by: Cursor <cursoragent@cursor.com>

refactor: apply suggestions from code review

ca15f59

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

jimmyandrade force-pushed the feat/webfont-mcp branch from 2a23cf3 to 0c4a606 Compare July 10, 2026 13:15

jimmyandrade changed the title ~~feat(webfont-mcp): add MCP server and public options reference API~~ feat(webfont-mcp): add MCP server, was tools, and public exports Jul 10, 2026

jimmyandrade and others added 2 commits July 10, 2026 10:24

test: remove obsolete standalone unicode snapshot

ae18688

Drop duplicate snapshot 2 left from an accidental update; the async glyphTransformFn test only asserts one template snapshot. Co-authored-by: Cursor <cursoragent@cursor.com>

chore(webfont-mcp): add portable Cursor MCP project config

0886284

Ship .cursor/mcp.json with ${workspaceFolder} so contributors can enable the local webfont MCP without machine-specific absolute paths. Co-authored-by: Cursor <cursoragent@cursor.com>

jimmyandrade requested a review from Copilot July 13, 2026 12:38

Copilot started reviewing on behalf of jimmyandrade July 13, 2026 12:39 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Comment thread packages/webfont-mcp/src/loadWasConfigInput.ts

jimmyandrade requested a review from Copilot July 13, 2026 20:58

Copilot started reviewing on behalf of jimmyandrade July 13, 2026 20:59 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(webfont-mcp): add MCP server, was tools, and public exports#796

feat(webfont-mcp): add MCP server, was tools, and public exports#796
jimmyandrade wants to merge 7 commits into
masterfrom
feat/webfont-mcp

jimmyandrade commented Jul 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jimmyandrade commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Proposed changes

Related issue

Dependencies added/removed (if applicable)

Testing

How to test

Test configuration

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jimmyandrade commented Jul 7, 2026 •

edited

Loading