typedump 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# typedump
+
+A curated index of open-source typefaces for designers — with metadata, utilities, and an MCP server for AI coding agents.
+
+144 hand-picked fonts across three collections: **Text** (interfaces, editorial, code), **Display** (headlines, posters, culture), and **Brutal** (experimental, pixel, raw). All fonts are bundled as woff2 — no external dependencies, no CDN, works offline.
+
+## Install
+
+```bash
+npm install typedump
+```
+
+## MCP Server
+
+Connect your AI coding agent to the TypeDump font library. The agent can search fonts, get code snippets, suggest pairings, and more — all from within your project.
+
+### Claude Code
+
+Add to your `claude.json` or run:
+
+```bash
+claude mcp add typedump -- npx typedump-mcp
+```
+
+### Cursor / Windsurf / VS Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "typedump": {
+      "command": "npx",
+      "args": ["typedump-mcp"]
+    }
+  }
+}
+```
+
+### What the agent can do
+
+Once connected, your agent can answer questions like:
+
+- *"Suggest a neutral sans for a fintech dashboard"*
+- *"What pairs well with Nyght Serif as a body font?"*
+- *"Give me the Next.js config for Geist"*
+- *"Find fonts similar to Cabinet Grotesk"*
+- *"Show me variable display fonts for a culture zine"*
+
+### Available tools
+
+| Tool | What it does |
+|---|---|
+| `search_fonts` | Search by name, use case, collection, category, or variable flag |
+| `get_font` | Full details: variants, variable axes, OpenType features |
+| `suggest_font` | Natural language → top font matches with reasoning |
+| `find_similar` | Fonts visually similar to a given font |
+| `pair_fonts` | Headline + body pairings, optionally anchored to a font you already use |
+| `get_code` | Ready code for CSS, Next.js `localFont`, or Tailwind |
+
+## JavaScript / TypeScript API
+
+```ts
+import { search, suggest, findSimilar, pairFonts, getCode, findFont } from 'typedump'
+
+// Search
+const results = search('neutral sans', { isVariable: true })
+
+// Suggest by description
+const picks = suggest('clean sans for a SaaS dashboard', 3)
+
+// Get code
+const snippet = getCode('Geist', 'nextjs')
+
+// Find similar fonts
+const similar = findSimilar('Cabinet Grotesk', 5)
+
+// Suggest pairings
+const pairings = pairFonts('Nyght Serif')
+
+// Full font details
+const font = findFont('Instrument Sans')
+```
+
+## Collections
+
+**Text** — fonts built for reading and interfaces. Neutral grotesques, humanist sans, editorial serifs, monospaces.
+
+**Display** — fonts with a strong point of view. Brand headlines, poster type, culture-driven display faces, scripts.
+
+**Brutal** — fonts that push limits. Pixel, experimental, raw, and culture-underground.
+
+## Use Cases
+
+Each font is tagged with one or more use cases:
+
+| Use case | What it's for |
+|---|---|
+| `Interface` | Neutral, balanced — product UI, dashboards, apps |
+| `Editorial / Ecommerce` | Humanist or characterful — shops, magazines, brand sites |
+| `Editorial` | Long-form reading — articles, books, newspapers |
+| `Code / Data` | Monospace — terminals, tables, developer tools |
+| `Brand Headline` | Strong display — logos, marketing, editorial titles |
+| `Poster` | Maximum impact — large type only |
+| `Culture` | Zines, art, independent press, identity |
+| `Tech / Digital` | Pixel, screen-native, digital culture |
+| `Handwritten / Script` | Calligraphy, personal, organic accents |
+| `Experimental` | Avant-garde, provocative, art projects |
+
+## Font files
+
+All fonts are bundled as woff2 inside the package at `node_modules/typedump/fonts/`. The `get_code` tool (and `getCode` function) generates copy commands and snippets that reference these files directly — no internet connection required.
+
+## License
+
+The package code is MIT. Each font has its own license (SIL OFL, Apache 2.0, or similar open-source). License info is included in the font metadata.