@ship-with-ai/stackmap-mcp 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShipWithAI (Alessandro Magionami & Manuel Salvatore Martone)
+
+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,44 @@
+# @ship-with-ai/stackmap-mcp
+
+Query **[StackMap](https://stackmap.shipwithai.xyz)** — the curated map of the open-source AI stack — from any MCP client. 200+ repos, every connection typed (`complements` / `alternative` / `built_with`) and human-reviewed, with the *why* written down — including **when NOT to use a tool**.
+
+No auth. No state. No telemetry. Reads the site's static JSON API; the catalog is date-versioned (`v2026.07.24` style) so you always know how fresh the map is.
+
+## Install
+
+**Claude Code**
+
+```bash
+claude mcp add stackmap -- npx -y @ship-with-ai/stackmap-mcp
+```
+
+**Cursor** — `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "stackmap": { "command": "npx", "args": ["-y", "stackmap-mcp"] } } }
+```
+
+**Codex CLI** — `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.stackmap]
+command = "npx"
+args = ["-y", "stackmap-mcp"]
+```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `search_catalog` | "What's on the map for *local voice transcription*?" |
+| `get_repo` | "Tell me about langgraph — including when NOT to use it." |
+| `get_alternatives` | "What replaces crewai, and when do I pick which?" |
+| `continue_stack` | "I use langgraph + chroma — what pairs well next?" |
+
+Every answer carries the curator's written why — the sentence a colleague would tell you over your shoulder, not a link dump.
+
+## How the data is made
+
+Nothing on the map auto-publishes: an LLM proposes, a human approves, sharpens, or refuses — and both the [refusal ledger and the dismissal ledger are public](https://stackmap.shipwithai.xyz/how-we-curate). Suggest a repo at [/suggest](https://stackmap.shipwithai.xyz/suggest); dispute any edge from its repo page.
+
+MIT · by [ShipWithAI](https://stackmap.shipwithai.xyz/about)

package/index.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// stackmap-mcp — query the StackMap catalog (stackmap.shipwithai.xyz) from any MCP client.
+// Reads the site's static JSON API; no auth, no state, no telemetry. The catalog is
+// CalVer-stamped (meta.version = date of last content change) and every relationship is
+// typed + human-reviewed with a written "why".
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+const SITE = process.env.STACKMAP_SITE_URL?.replace(/\/+$/, '') || 'https://stackmap.shipwithai.xyz'
+const TTL_MS = 15 * 60 * 1000
+
+let _cache = null // { at, catalog }
+async function catalog() {
+  if (_cache && Date.now() - _cache.at < TTL_MS) return _cache.catalog
+  const res = await fetch(`${SITE}/api/catalog.json`)
+  if (!res.ok) throw new Error(`catalog fetch failed: HTTP ${res.status}`)
+  const c = await res.json()
+  _cache = { at: Date.now(), catalog: c }
+  return c
+}
+
+const stamp = c => `StackMap catalog v${c.version || '?'} · ${Object.keys(c.repos).length} repos · every connection human-reviewed`
+const text = s => ({ content: [{ type: 'text', text: s }] })
+const fail = s => ({ content: [{ type: 'text', text: s }], isError: true })
+
+// Compact, citable card for one repo — the shape every tool answers with.
+function card(c, slug, { withEdges = true } = {}) {
+  const r = c.repos[slug]
+  if (!r) return null
+  const head = `## ${r.name} (${r.owner}/${slug}) — ★${(r.stars || 0).toLocaleString('en-US')}${r.language ? ` · ${r.language}` : ''}${(r.topics || []).length ? ` · ${r.topics.join(', ')}` : ''}`
+  const lines = [head, '', r.summary || '', '', `**Curator's take:** ${r.curator_note || '(none)'}`]
+  if (withEdges) {
+    const rel = r.related || {}
+    for (const [type, label] of [['complements', 'Pairs well with'], ['alternative', 'Alternatives'], ['built_with', 'Built with / foundation for']]) {
+      const items = rel[type] || []
+      if (!items.length) continue
+      lines.push('', `**${label}:**`)
+      for (const e of items) lines.push(`- ${e.name} (${e.slug}) — ${e.why}`)
+    }
+  }
+  lines.push('', `Page: ${r.url || `${SITE}/repos/${r.owner}/${slug}`}`)
+  return lines.join('\n')
+}
+
+function score(r, terms) {
+  const hay = [r.name, r.slug, r.summary, r.curator_note, (r.topics || []).join(' ')].join(' ').toLowerCase()
+  let s = 0
+  for (const t of terms) {
+    if (!hay.includes(t)) return 0            // AND semantics — every term must appear
+    s += (r.name?.toLowerCase().includes(t) ? 3 : 0) + (r.summary?.toLowerCase().includes(t) ? 2 : 1)
+  }
+  return s + Math.log10((r.stars || 0) + 10)  // tie-break by popularity, gently
+}
+
+const server = new McpServer({ name: 'stackmap', version: '0.1.0' })
+
+server.registerTool('search_catalog', {
+  title: 'Search the StackMap catalog',
+  description: 'Search 200+ curated open-source AI/agent repos by keywords. Matches name, summary, curator note and topics. Returns ranked matches with the human-written "when to use it (and when not)".',
+  inputSchema: { query: z.string().describe('keywords, e.g. "local voice transcription" or "agent memory"'), limit: z.number().int().min(1).max(25).optional().describe('max results (default 8)') },
+}, async ({ query, limit = 8 }) => {
+  const c = await catalog()
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+  if (!terms.length) return fail('empty query')
+  const hits = Object.entries(c.repos)
+    .map(([slug, r]) => ({ slug, r, s: score(r, terms) }))
+    .filter(h => h.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+  if (!hits.length) return text(`No matches for "${query}". ${stamp(c)}\nTry broader terms, or browse topics: ${Object.keys(c.topics).join(', ')}.`)
+  const body = hits.map(h => `- **${h.r.name}** (${h.slug}) ★${(h.r.stars || 0).toLocaleString('en-US')} — ${h.r.summary}`).join('\n')
+  return text(`${stamp(c)}\n\n${body}\n\nUse get_repo(slug) for the curator's take and typed relationships.`)
+})
+
+server.registerTool('get_repo', {
+  title: 'Get one repo, fully mapped',
+  description: 'Full StackMap entry for a repo: summary, the opinionated curator note (including when NOT to use it), and every typed, human-reviewed relationship with its written why.',
+  inputSchema: { slug: z.string().describe('repo slug, e.g. "langgraph" (try search_catalog if unsure)') },
+}, async ({ slug }) => {
+  const c = await catalog()
+  const k = slug.toLowerCase()
+  const out = card(c, k)
+  if (!out) return fail(`Unknown slug "${slug}". Use search_catalog to find it.`)
+  return text(`${stamp(c)}\n\n${out}`)
+})
+
+server.registerTool('get_alternatives', {
+  title: 'Alternatives to a repo',
+  description: 'Human-reviewed alternatives for a repo — same job, different tool — each with the written "when to pick which".',
+  inputSchema: { slug: z.string().describe('repo slug') },
+}, async ({ slug }) => {
+  const c = await catalog()
+  const r = c.repos[slug.toLowerCase()]
+  if (!r) return fail(`Unknown slug "${slug}". Use search_catalog to find it.`)
+  const alts = r.related?.alternative || []
+  if (!alts.length) return text(`${stamp(c)}\n\nNo curated alternatives recorded for ${r.name} yet — an honest gap, not an oversight. Compare pages: ${SITE}/alternatives/${slug}`)
+  const body = alts.map(e => `- **${e.name}** (${e.slug}) — ${e.why}`).join('\n')
+  return text(`${stamp(c)}\n\n**Alternatives to ${r.name}:**\n${body}`)
+})
+
+server.registerTool('continue_stack', {
+  title: 'Continue your stack',
+  description: 'Given repos you already use, suggests what pairs well next — curated complements ranked by curator confidence, each with the written why.',
+  inputSchema: { slugs: z.array(z.string()).min(1).describe('repo slugs already in your stack, e.g. ["langgraph","chroma"]') },
+}, async ({ slugs }) => {
+  const c = await catalog()
+  const have = new Set(slugs.map(s => s.toLowerCase()))
+  const unknown = [...have].filter(s => !c.repos[s])
+  const candidates = new Map() // slug -> { conf, whys: [from → why] }
+  for (const s of have) {
+    const r = c.repos[s]
+    if (!r) continue
+    for (const e of r.related?.complements || []) {
+      if (have.has(e.slug)) continue
+      const cur = candidates.get(e.slug) || { conf: 0, whys: [] }
+      cur.conf = Math.max(cur.conf, e.confidence || 0)
+      cur.whys.push(`with ${r.name}: ${e.why}`)
+      candidates.set(e.slug, cur)
+    }
+  }
+  const ranked = [...candidates.entries()].sort((a, b) => b[1].conf - a[1].conf).slice(0, 8)
+  const parts = [stamp(c)]
+  if (unknown.length) parts.push(`(unknown slugs ignored: ${unknown.join(', ')})`)
+  if (!ranked.length) return text(`${parts.join('\n')}\n\nNo curated complements found beyond what you have. Browse the graph: ${SITE}/`)
+  parts.push('', '**What pairs well next:**')
+  for (const [slug, { whys }] of ranked) {
+    const r = c.repos[slug]
+    parts.push(`- **${r.name}** (${slug}) ★${(r.stars || 0).toLocaleString('en-US')}`)
+    for (const w of whys) parts.push(`  - ${w}`)
+  }
+  return text(parts.join('\n'))
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ship-with-ai/stackmap-mcp",
+  "version": "0.1.2",
+  "description": "MCP server for StackMap \u2014 the curated map of the open-source AI stack. Search 200+ human-reviewed repos, typed relationships (complements / alternative / built_with), and the written why behind every connection.",
+  "type": "module",
+  "bin": {
+    "stackmap-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "ai",
+    "agents",
+    "stackmap",
+    "curated",
+    "knowledge-graph"
+  ],
+  "author": "ShipWithAI",
+  "license": "MIT",
+  "homepage": "https://stackmap.shipwithai.xyz",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ship-With-AI/stackmap-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ship-With-AI/stackmap-mcp/issues"
+  }
+}