mcp-fmt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tortuga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# mcp-fmt
+
+Format MCP tool results into markdown that renders in Claude Code's terminal.
+
+> Built by [Tortuga](https://bytortuga.com)
+
+## Why
+
+MCP tools return raw text. Without formatting, Claude Code displays unreadable walls of data. `mcp-fmt` gives you the markdown primitives that Claude Code's terminal actually renders — tables, lists, headers, code blocks, bold/italic — nothing more, nothing less.
+
+## Screenshots
+
+| Claude Code | Cursor | Codex |
+|---|---|---|
+| Coming soon | Coming soon | Coming soon |
+
+## Install
+
+```bash
+npm install mcp-fmt
+# or
+bun add mcp-fmt
+```
+
+## Usage
+
+### `table(headers, rows, totalRow?)`
+
+Raw string arrays with an optional bold total row.
+
+```ts
+import { table } from 'mcp-fmt'
+
+table(
+  ['Task', 'Owner', 'Points'],
+  [
+    ['Init repo',     'alice', '3'],
+    ['Add formatter', 'bob',   '5'],
+  ],
+  ['Total', '', '8']
+)
+```
+
+### `table(rows)` — object overload
+
+Pass an array of objects and headers are inferred from keys.
+
+```ts
+table([
+  { id: 'QM-1', title: 'Init repo',     status: 'done'        },
+  { id: 'QM-2', title: 'Add formatter', status: 'in_progress' },
+])
+```
+
+### `section(title, ...content)`
+
+Composes a titled block from a heading and content strings. The core building block for tool responses.
+
+```ts
+import { section, table } from 'mcp-fmt'
+
+section(
+  'Sprint Summary',
+  'By Owner:',
+  table(headers, rows, totals),
+  '',
+  '1 done · 2 in progress'
+)
+```
+
+### `list(items, ordered?)`
+
+```ts
+import { list } from 'mcp-fmt'
+
+list(['Install mcp-fmt', 'Import formatters', 'Return formatted text'])
+list(['First', 'Second', 'Third'], true)
+```
+
+### `keyValue(data)`
+
+Renders an object as a two-column key/value table.
+
+```ts
+import { keyValue } from 'mcp-fmt'
+
+keyValue({ status: 'active', owner: 'alice', points: 8 })
+```
+
+### `statusBadge(status)`
+
+```ts
+import { statusBadge } from 'mcp-fmt'
+
+statusBadge('completed')   // ✅
+statusBadge('in_progress') // 🚀
+statusBadge('blocked')     // 🚫
+statusBadge('on_hold')     // ⏸️
+statusBadge('reviewing')   // 🔍
+statusBadge('syncing')     // 🔄
+statusBadge('pending')     // 📤
+statusBadge('archived')    // 🗑️
+statusBadge('cancelled')   // ❌
+statusBadge('merged')      // 🔀
+```
+
+### `priorityBadge(priority)`
+
+```ts
+import { priorityBadge } from 'mcp-fmt'
+
+priorityBadge('low')       // 🟢
+priorityBadge('medium')    // 🟡
+priorityBadge('high')      // 🔴
+priorityBadge('urgent')    // 🔥
+```
+
+### `healthBadge(health)`
+
+```ts
+import { healthBadge } from 'mcp-fmt'
+
+healthBadge('healthy')     // 🟢
+healthBadge('degraded')    // 🟡
+healthBadge('warning')     // 🟠
+healthBadge('down')        // 🔴
+healthBadge('unknown')     // ⬜
+```
+
+### `typeBadge(type)`
+
+```ts
+import { typeBadge } from 'mcp-fmt'
+
+typeBadge('bug')           // 🐛
+typeBadge('feature')       // ✨
+typeBadge('docs')          // 📝
+typeBadge('chore')         // 🔧
+typeBadge('security')      // 🔒
+typeBadge('performance')   // ⚡
+typeBadge('test')          // 🧪
+typeBadge('refactor')      // ♻️
+```
+
+### `assignmentBadge(assignment)`
+
+```ts
+import { assignmentBadge } from 'mcp-fmt'
+
+assignmentBadge('unassigned') // 👤
+assignmentBadge('team')       // 👥
+assignmentBadge('automated')  // 🤖
+assignmentBadge('owner')      // 👑
+```
+
+### `codeBlock(code, lang?)`
+
+```ts
+import { codeBlock } from 'mcp-fmt'
+
+codeBlock(`const x = 1`, 'ts')
+```
+
+### `header(text, level?)`, `bold(text)`, `italic(text)`
+
+```ts
+import { header, bold, italic } from 'mcp-fmt'
+
+header('My Tool')          // ## My Tool
+header('My Tool', 1)       // # My Tool
+bold('Total: 42')          // **Total: 42**
+italic('optional')         // _optional_
+```
+
+## Full MCP Tool Example
+
+```ts
+import { table, section, bold } from 'mcp-fmt'
+
+server.tool('summary', {}, async () => {
+  const headers = ['Task', 'Owner', 'Status', 'Points']
+  const rows = [
+    ['Init repo',     'alice', 'done',        '3'],
+    ['Add formatter', 'bob',   'in_progress', '5'],
+    ['Write tests',   'alice', 'backlog',     '2'],
+  ]
+  const totals = ['Total', '', '', '10']
+
+  return {
+    content: [{
+      type: 'text',
+      text: section(
+        'Sprint Summary',
+        'By Owner:',
+        table(headers, rows, totals),
+        '',
+        bold('Velocity: ') + '10 pts'
+      )
+    }]
+  }
+})
+```
+
+## API Reference
+
+| Export | Signature | Description |
+| --- | --- | --- |
+| `table` | `(headers, rows, totalRow?)` | Markdown table from string arrays; totalRow is bolded |
+| `table` | `(rows: Row[])` | Convenience overload — infers headers from object keys |
+| `section` | `(title, ...content)` | H2 title + content joined with newlines |
+| `list` | `(items, ordered?)` | Unordered or ordered list |
+| `nestedList` | `(items)` | Two-level nested list |
+| `keyValue` | `(data: Row)` | Object rendered as a key/value table |
+| `statusBadge` | `(status)` | Emoji for status values (backlog, in_progress, completed, blocked, on_hold, syncing, pending, reviewing, archived, cancelled, merged) |
+| `priorityBadge` | `(priority)` | Emoji for priority values (low, medium, high, urgent) |
+| `healthBadge` | `(health)` | Emoji for health/monitoring (healthy, degraded, warning, down, unknown) |
+| `typeBadge` | `(type)` | Emoji for issue types (bug, feature, docs, chore, security, performance, test, refactor) |
+| `assignmentBadge` | `(assignment)` | Emoji for assignment (unassigned, team, automated, owner) |
+| `codeBlock` | `(code, lang?)` | Fenced code block with optional language |
+| `inlineCode` | `(code)` | Backtick-wrapped inline code |
+| `header` | `(text, level?)` | H1–H3 markdown header (default: H2) |
+| `bold` | `(text)` | Bold text |
+| `italic` | `(text)` | Italic text |
+
+## Previewing the output
+
+Markdown only renders inside AI chat responses, not in terminal output. To see how your formatting looks, use the bundled preview MCP server.
+
+**1. Clone the repo**
+
+```bash
+git clone https://github.com/tortuga-ai/mcp-fmt.git
+```
+
+**2. Add to your MCP config**
+
+Claude Code (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-fmt-preview": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "./examples/preview-mcp.ts"]
+    }
+  }
+}
+```
+
+Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-fmt-preview": {
+      "command": "bun",
+      "args": ["run", "./examples/preview-mcp.ts"]
+    }
+  }
+}
+```
+
+**3. Restart your AI agent, then ask:** `call the preview tool`
+
+It will render all primitives as markdown in the chat response.
+
+## License
+
+MIT License - see LICENSE for details.
+
+## Author
+
+[Josh Grenon](https://github.com/joshgrenon)
+
+---
+
+![](.github/tortuga.png)

package/dist/code.d.ts

@@ -0,0 +1,2 @@
+export declare function codeBlock(code: string, lang?: string): string;
+export declare function inlineCode(code: string): string;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { table } from './table';
+export type { Row } from './table';
+export { list, nestedList } from './list';
+export { codeBlock, inlineCode } from './code';
+export { header, bold, italic } from './text';
+export { section } from './section';
+export { keyValue } from './keyvalue';
+export { statusBadge, priorityBadge, healthBadge, typeBadge, assignmentBadge } from './status';
+export type { Status, Priority, Health, IssueType, Assignment } from './status';

package/dist/index.js

@@ -0,0 +1,139 @@
+// src/table.ts
+function table(headersOrRows, maybeRows, totalRow) {
+  if (maybeRows !== undefined) {
+    const headers2 = headersOrRows;
+    const lines = [
+      `| ${headers2.join(" | ")} |`,
+      `| ${headers2.map(() => "---").join(" | ")} |`,
+      ...maybeRows.map((r) => `| ${r.join(" | ")} |`),
+      ...totalRow ? [`| ${totalRow.map((v) => v ? `**${v}**` : "").join(" | ")} |`] : []
+    ];
+    return lines.join(`
+`);
+  }
+  const objRows = headersOrRows;
+  if (objRows.length === 0)
+    return "";
+  const headers = Object.keys(objRows[0]);
+  const rows = objRows.map((r) => headers.map((h) => String(r[h] ?? "")));
+  return table(headers, rows);
+}
+// src/list.ts
+function list(items, ordered = false) {
+  return items.map((item, i) => ordered ? `${i + 1}. ${item}` : `- ${item}`).join(`
+`);
+}
+function nestedList(items) {
+  return items.map(({ text, children }) => {
+    const line = `- ${text}`;
+    if (!children?.length)
+      return line;
+    return [line, ...children.map((c) => `  - ${c}`)].join(`
+`);
+  }).join(`
+`);
+}
+// src/code.ts
+function codeBlock(code, lang = "") {
+  return `\`\`\`${lang}
+${code}
+\`\`\``;
+}
+function inlineCode(code) {
+  return `\`${code}\``;
+}
+// src/text.ts
+function header(text, level = 2) {
+  return `${"#".repeat(level)} ${text}`;
+}
+function bold(text) {
+  return `**${text}**`;
+}
+function italic(text) {
+  return `_${text}_`;
+}
+// src/section.ts
+function section(title, ...content) {
+  return [header(title, 2), ...content].join(`
+`);
+}
+// src/keyvalue.ts
+function keyValue(data) {
+  const rows = Object.entries(data).map(([k, v]) => [k, v == null ? "" : String(v)]);
+  return table(["Key", "Value"], rows);
+}
+// src/status.ts
+var STATUS_EMOJI = {
+  backlog: "\uD83D\uDCCB",
+  in_progress: "\uD83D\uDE80",
+  completed: "✅",
+  blocked: "\uD83D\uDEAB",
+  on_hold: "⏸️",
+  syncing: "\uD83D\uDD04",
+  pending: "\uD83D\uDCE4",
+  reviewing: "\uD83D\uDD0D",
+  archived: "\uD83D\uDDD1️",
+  cancelled: "❌",
+  merged: "\uD83D\uDD00"
+};
+var PRIORITY_EMOJI = {
+  low: "\uD83D\uDFE2",
+  medium: "\uD83D\uDFE1",
+  high: "\uD83D\uDD34",
+  urgent: "\uD83D\uDD25"
+};
+var HEALTH_EMOJI = {
+  healthy: "\uD83D\uDFE2",
+  down: "\uD83D\uDD34",
+  degraded: "\uD83D\uDFE1",
+  warning: "\uD83D\uDFE0",
+  unknown: "⬜"
+};
+var TYPE_EMOJI = {
+  bug: "\uD83D\uDC1B",
+  feature: "✨",
+  docs: "\uD83D\uDCDD",
+  chore: "\uD83D\uDD27",
+  security: "\uD83D\uDD12",
+  performance: "⚡",
+  test: "\uD83E\uDDEA",
+  refactor: "♻️"
+};
+var ASSIGNMENT_EMOJI = {
+  unassigned: "\uD83D\uDC64",
+  team: "\uD83D\uDC65",
+  automated: "\uD83E\uDD16",
+  owner: "\uD83D\uDC51"
+};
+function statusBadge(status) {
+  return STATUS_EMOJI[status] ?? "\uD83D\uDCCB";
+}
+function priorityBadge(priority) {
+  return PRIORITY_EMOJI[priority] ?? "\uD83D\uDFE1";
+}
+function healthBadge(health) {
+  return HEALTH_EMOJI[health] ?? "⬜";
+}
+function typeBadge(type) {
+  return TYPE_EMOJI[type] ?? "\uD83D\uDCDD";
+}
+function assignmentBadge(assignment) {
+  return ASSIGNMENT_EMOJI[assignment] ?? "\uD83D\uDC64";
+}
+export {
+  typeBadge,
+  table,
+  statusBadge,
+  section,
+  priorityBadge,
+  nestedList,
+  list,
+  keyValue,
+  italic,
+  inlineCode,
+  healthBadge,
+  header,
+  codeBlock,
+  bold,
+  assignmentBadge
+};

package/dist/keyvalue.d.ts

@@ -0,0 +1,2 @@
+import type { Row } from './table';
+export declare function keyValue(data: Row): string;

package/dist/list.d.ts

@@ -0,0 +1,5 @@
+export declare function list(items: string[], ordered?: boolean): string;
+export declare function nestedList(items: Array<{
+    text: string;
+    children?: string[];
+}>): string;

package/dist/section.d.ts

@@ -0,0 +1 @@
+export declare function section(title: string, ...content: string[]): string;

package/dist/status.d.ts

@@ -0,0 +1,10 @@
+export type Status = 'backlog' | 'in_progress' | 'completed' | 'blocked' | 'on_hold' | 'syncing' | 'pending' | 'reviewing' | 'archived' | 'cancelled' | 'merged';
+export type Priority = 'low' | 'medium' | 'high' | 'urgent';
+export type Health = 'healthy' | 'down' | 'degraded' | 'warning' | 'unknown';
+export type IssueType = 'bug' | 'feature' | 'docs' | 'chore' | 'security' | 'performance' | 'test' | 'refactor';
+export type Assignment = 'unassigned' | 'team' | 'automated' | 'owner';
+export declare function statusBadge(status: Status | string): string;
+export declare function priorityBadge(priority: Priority | string): string;
+export declare function healthBadge(health: Health | string): string;
+export declare function typeBadge(type: IssueType | string): string;
+export declare function assignmentBadge(assignment: Assignment | string): string;

package/dist/table.d.ts

@@ -0,0 +1,3 @@
+export type Row = Record<string, string | number | boolean | null | undefined>;
+export declare function table(headers: string[], rows: string[][], totalRow?: string[]): string;
+export declare function table(rows: Row[]): string;

package/dist/text.d.ts

@@ -0,0 +1,3 @@
+export declare function header(text: string, level?: 1 | 2 | 3): string;
+export declare function bold(text: string): string;
+export declare function italic(text: string): string;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mcp-fmt",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "description": "Format MCP tool results into markdown that renders in Claude Code's terminal",
+  "keywords": [
+    "mcp",
+    "markdown",
+    "terminal",
+    "claude",
+    "formatting"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tortuga-ai/mcp-fmt.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "example": "bun run examples/basic.ts"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts"
+}