Skip to content
Back to search

gridsmith

MarketplaceWorks with Claude CodeGitHub

Generate geometric SVG logos, UI icons and magic circles from a JSON construction spec: an MCP server and TypeScript library

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/libraz--gridsmith/badge.svg)](/listings/libraz--gridsmith)

HTML

<a href="/listings/libraz--gridsmith"><img src="/api/listings/libraz--gridsmith/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 24 or later. Register the MCP server with Claude Code and/or Codex CLI:

npx -y github:libraz/gridsmith init

`init` asks which configs to update and writes only the `gridsmith` entry; `uninstall` removes it. In Claude Code it also installs as a plugin:

/plugin install gridsmith --marketplace libraz/gridsmith

Manual setup for other clients is in [Getting started](https://github.com/libraz/gridsmith/blob/main/docs/en/getting-started.md).

As a library:

npm install github:libraz/gridsmith

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines
  1. {
  2. "name": "gridsmith",
  3. "metadata": {
  4. "description": "Geometric SVG logos, UI icons and magic-circle figures from a JSON construction spec, for Claude Code."
  5. },
  6. "owner": {
  7. "name": "libraz",
  8. "email": "libraz@libraz.net",
  9. "url": "https://github.com/libraz"
  10. },
  11. "plugins": [
  12. {
  13. "name": "gridsmith",
  14. "source": "./",
  15. "description": "MCP server that draws logo marks, magic-circle figures and 24-unit UI icons from a JSON construction spec.",
  16. "version": "0.1.0",
  17. "homepage": "https://github.com/libraz/gridsmith",
  18. "license": "Apache-2.0",
  19. "keywords": ["mcp", "svg", "logo", "icon", "geometry", "magic-circle"]
  20. }
  21. ]
  22. }
README.md · README · 110 lines
  1. # gridsmith
  2. [![CI](https://img.shields.io/github/actions/workflow/status/libraz/gridsmith/ci.yml?branch=main&label=CI)](https://github.com/libraz/gridsmith/actions)
  3. [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/libraz/gridsmith/blob/main/LICENSE)
  4. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  5. [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A524-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
  6. **gridsmith generates geometric SVG logos, 24 px UI icons and magic-circle figures from a JSON construction spec, as an MCP server for AI assistants and as a TypeScript library.** The spec declares circles on a grid, tangent circles, lines, arcs and regular polygons; gridsmith solves the geometry, lints it against construction rules (few radius ratios, a coarse grid, n-fold symmetry) and renders SVG and PNG with a construction sheet. A model that writes the spec gets exact tangents and intersections instead of guessed coordinates.
  7. 📖 **[Documentation](https://github.com/libraz/gridsmith/blob/main/docs/en/getting-started.md)** &nbsp;·&nbsp; **[Gallery](https://github.com/libraz/gridsmith/blob/main/docs/en/gallery.md)** &nbsp;·&nbsp; **[Library API](https://github.com/libraz/gridsmith/blob/main/docs/en/api-reference.md)**
  8. > Pre-1.0: the spec grammar and the rule thresholds may still change.
  9. <p>
  10. <img src="https://raw.githubusercontent.com/libraz/gridsmith/main/docs/gallery/whale-sheet.png" alt="Construction sheet of a whale logo mark built from tangent circles" width="260">
  11. <img src="https://raw.githubusercontent.com/libraz/gridsmith/main/docs/gallery/sigil-medallions-sheet.png" alt="Construction sheet of a magic-circle figure with medallions on a ring" width="260">
  12. <img src="https://raw.githubusercontent.com/libraz/gridsmith/main/docs/gallery/line-chart-sheet.png" alt="Construction sheet of a line-chart UI icon on its 24-unit grid" width="260">
  13. </p>
  14. ## What's inside
  15. - **Logo marks** — filled regions from unions, intersections and differences of discs, polygons and half-planes, previewed at 64, 32 and 16 px. [Spec format](https://github.com/libraz/gridsmith/blob/main/docs/en/spec.md)
  16. - **Magic-circle figures** — stroked rings, stars, arcs and repeated medallions, with erase layers that cut bands. [Gallery](https://github.com/libraz/gridsmith/blob/main/docs/en/gallery.md)
  17. - **UI icons** — 24-unit icons mixing fills and strokes, exported as SVG, PNG and per-layer path segments. [Icons](https://github.com/libraz/gridsmith/blob/main/docs/en/icons.md)
  18. - **SVG icon import** — converts the paths of an existing icon into a spec rounded to the grid, with the pixel difference from the original. [Icons](https://github.com/libraz/gridsmith/blob/main/docs/en/icons.md)
  19. - **Construction rules** — a lint pass reports off-grid values, too many ratios, angles off the allowed divisions and thin strokes; a spec exports only once it is clean. [Rules](https://github.com/libraz/gridsmith/blob/main/docs/en/spec.md#rules)
  20. - **Reference matching** — overlays a PNG or JPEG on the drawing and scores the overlap, so a silhouette can be traced. [Outlines and underlay](https://github.com/libraz/gridsmith/blob/main/docs/en/spec.md#outlines-and-underlay)
  21. - **Four MCP tools** — `gridsmith_guide`, `gridsmith_render`, `gridsmith_export`, `gridsmith_import` over stdio. [MCP tools](https://github.com/libraz/gridsmith/blob/main/docs/en/mcp-tools.md)
  22. ## Installation
  23. Requires Node.js 24 or later. Register the MCP server with Claude Code and/or Codex CLI:
  24. ```sh
  25. npx -y github:libraz/gridsmith init
  26. ```
  27. `init` asks which configs to update and writes only the `gridsmith` entry; `uninstall` removes it. In Claude Code it also installs as a plugin:
  28. ```text
  29. /plugin install gridsmith --marketplace libraz/gridsmith
  30. ```
  31. Manual setup for other clients is in [Getting started](https://github.com/libraz/gridsmith/blob/main/docs/en/getting-started.md).
  32. As a library:
  33. ```sh
  34. npm install github:libraz/gridsmith
  35. ```
  36. ## Quick start
  37. ### MCP
  38. Ask the assistant for a mark, a figure or an icon. It reads `gridsmith_guide`, writes the spec to a JSON file, iterates with `gridsmith_render` until the report shows no violations, then writes the files with `gridsmith_export`.
  39. ### TypeScript
  40. ```ts
  41. import { mkdtemp, writeFile } from 'node:fs/promises';
  42. import { tmpdir } from 'node:os';
  43. import { join } from 'node:path';
  44. import { render } from '@libraz/gridsmith';
  45. const drawing = render({
  46. version: 1,
  47. mode: 'mark',
  48. grid: { divisions: 4 },
  49. shapes: [
  50. { id: 'body', type: 'circle', r: 'R' },
  51. { id: 'bite', type: 'circle', center: [1, 1], r: 3 },
  52. ],
  53. paint: [{ fill: { subtract: ['body', 'bite'] } }],
  54. });
  55. console.log(drawing.violations); // [] when every rule passes
  56. const out = await mkdtemp(join(tmpdir(), 'gridsmith-'));
  57. await writeFile(join(out, 'crescent.svg'), drawing.svg);
  58. await writeFile(join(out, 'crescent-64.png'), drawing.png(64));
  59. ```
  60. → [Library API](https://github.com/libraz/gridsmith/blob/main/docs/en/api-reference.md)
  61. ## Build from source
  62. ```sh
  63. yarn install && yarn build # compiles src/ to dist/
  64. yarn test # Vitest, including the examples in README.md and docs/en/
  65. yarn check # Biome and tsc --noEmit
  66. yarn gallery # rebuilds docs/gallery/ from src/guide/examples.ts
  67. ```
  68. The files in `docs/gallery/` are generated; do not edit them by hand.
  69. ## Documentation
  70. The docs are Markdown under `docs/en/` and `docs/ja/`.
  71. - **Learn** — [Getting started](https://github.com/libraz/gridsmith/blob/main/docs/en/getting-started.md) · [Gallery](https://github.com/libraz/gridsmith/blob/main/docs/en/gallery.md)
  72. - **Guides** — [Spec format](https://github.com/libraz/gridsmith/blob/main/docs/en/spec.md) · [Icons](https://github.com/libraz/gridsmith/blob/main/docs/en/icons.md)
  73. - **Reference** — [MCP tools](https://github.com/libraz/gridsmith/blob/main/docs/en/mcp-tools.md) · [Library API](https://github.com/libraz/gridsmith/blob/main/docs/en/api-reference.md)
  74. ## Non-goals
  75. gridsmith draws geometry only. It does not render text: finished drawings contain no glyphs. It does not trace bitmaps automatically; an underlay is scored against a drawing the spec describes.
  76. ## License
  77. [Apache-2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.