@stacksfinder/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,262 @@
+# @stacksfinder/mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@stacksfinder/mcp-server.svg)](https://www.npmjs.com/package/@stacksfinder/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+MCP (Model Context Protocol) server that brings **deterministic tech stack recommendations** to LLM clients like Claude, Cursor, Windsurf, and other MCP-compatible tools.
+
+**Try it free** — 4 tools work without an account, including a daily demo recommendation.
+
+## Quick Start
+
+### Claude Code (CLI)
+
+```bash
+# Add to Claude Code
+claude mcp add stacksfinder npx -y @stacksfinder/mcp-server
+
+# With API key for full features
+claude mcp add-json stacksfinder '{
+  "command": "npx",
+  "args": ["-y", "@stacksfinder/mcp-server"],
+  "env": {"STACKSFINDER_API_KEY": "sk_live_xxx"}
+}'
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "stacksfinder": {
+      "command": "npx",
+      "args": ["-y", "@stacksfinder/mcp-server"],
+      "env": {
+        "STACKSFINDER_API_KEY": "sk_live_xxx"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+Add to `.cursor/mcp.json` or `.windsurf/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "stacksfinder": {
+      "command": "npx",
+      "args": ["-y", "@stacksfinder/mcp-server"],
+      "env": {
+        "STACKSFINDER_API_KEY": "sk_live_xxx"
+      }
+    }
+  }
+}
+```
+
+### VS Code + Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "stacksfinder": {
+      "command": "npx",
+      "args": ["-y", "@stacksfinder/mcp-server"],
+      "env": {
+        "STACKSFINDER_API_KEY": "sk_live_xxx"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Free Tools (no account required)
+
+| Tool | Description |
+|------|-------------|
+| `list_technologies` | List all 30+ tech IDs by category |
+| `analyze_tech` | 6-dimension scores, strengths, weaknesses, compatible techs |
+| `compare_techs` | Side-by-side comparison of 2-4 technologies |
+| `recommend_stack` | **FREE 1x/day** — Full stack recommendation for any project type |
+
+### Pro Tools (requires API key)
+
+| Tool | Description |
+|------|-------------|
+| `recommend_stack` | Unlimited recommendations with priorities & constraints |
+| `get_blueprint` | Fetch existing blueprint by ID |
+| `create_blueprint` | Generate new blueprint with AI narrative |
+| `setup_api_key` | Authenticate and create API key from MCP |
+| `list_api_keys` | List your API keys |
+| `revoke_api_key` | Revoke an API key |
+
+Get your API key at [stacksfinder.com/pricing](https://stacksfinder.com/pricing)
+
+## Tool Examples
+
+### list_technologies
+
+```
+> list_technologies category="database"
+
+Available databases:
+- postgres (PostgreSQL)
+- sqlite (SQLite)
+- supabase (Supabase)
+- planetscale (PlanetScale)
+- turso (Turso)
+- neon (Neon)
+```
+
+### analyze_tech
+
+```
+> analyze_tech technology="sveltekit" context="mvp"
+
+## SvelteKit Analysis (MVP Context)
+
+| Dimension | Score | Grade |
+|-----------|-------|-------|
+| Performance | 92 | A |
+| DX | 88 | A |
+| Ecosystem | 72 | B |
+| Maintainability | 85 | A |
+| Cost | 90 | A |
+| Compliance | 75 | B |
+
+**Overall: 84/100 (A)**
+
+Strengths:
+- Compiler-first architecture, tiny bundles
+- Excellent TypeScript support
+- Built-in SSR, SSG, and edge rendering
+
+Weaknesses:
+- Smaller ecosystem than React
+- Fewer enterprise case studies
+```
+
+### compare_techs
+
+```
+> compare_techs technologies=["nextjs", "sveltekit", "nuxt"]
+
+## Comparison: Next.js vs SvelteKit vs Nuxt
+
+| Tech | Score | Grade |
+|------|-------|-------|
+| Next.js | 82 | A |
+| SvelteKit | 84 | A |
+| Nuxt | 79 | B |
+
+Per-dimension winners:
+- Performance: SvelteKit (+10)
+- DX: SvelteKit (+3)
+- Ecosystem: Next.js (+15)
+```
+
+### recommend_stack (Free Demo)
+
+```
+> recommend_stack projectType="saas" scale="mvp"
+
+## Recommended Stack for SaaS (MVP)
+
+| Category | Technology | Score | Grade |
+|----------|------------|-------|-------|
+| meta-framework | SvelteKit | 84 | A |
+| database | Supabase | 82 | A |
+| orm | Drizzle | 86 | A |
+| auth | Better Auth | 80 | A |
+| hosting | Vercel | 85 | A |
+| payments | Paddle | 86 | A |
+
+**Confidence**: medium (demo mode)
+
+---
+Want more? Upgrade to Pro for custom priorities, constraints, and AI narratives.
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STACKSFINDER_API_KEY` | For Pro tools | - | API key from stacksfinder.com |
+| `STACKSFINDER_API_URL` | No | `https://stacksfinder.com` | API base URL |
+| `STACKSFINDER_MCP_DEBUG` | No | `false` | Enable debug logging |
+
+## Score Dimensions
+
+All technology scores are measured across 6 dimensions (0-100):
+
+| Dimension | Description |
+|-----------|-------------|
+| **Performance** | Runtime speed, bundle size, optimization potential |
+| **DX** | Learning curve, tooling, documentation quality |
+| **Ecosystem** | Community size, integrations, job market |
+| **Maintainability** | Long-term code health, upgrade path |
+| **Cost** | Hosting costs, licensing, operational overhead |
+| **Compliance** | Security features, audit readiness |
+
+## Contexts
+
+Scores vary by project context:
+
+- **default**: General-purpose scores
+- **mvp**: Optimized for speed-to-market, lower cost
+- **enterprise**: Emphasizes compliance, maintainability, support
+
+## Error Handling
+
+Structured errors with suggestions:
+
+```
+**Error (TECH_NOT_FOUND)**: Technology "nexjs" not found.
+**Suggestions**: nextjs, nuxt, nestjs
+```
+
+## Troubleshooting
+
+### Debug mode
+
+```bash
+STACKSFINDER_MCP_DEBUG=true npx @stacksfinder/mcp-server
+```
+
+### Common issues
+
+| Issue | Solution |
+|-------|----------|
+| "API key required" | Get key at [stacksfinder.com/pricing](https://stacksfinder.com/pricing) |
+| "Daily limit reached" | Wait 24h or upgrade to Pro |
+| "Technology not found" | Use `list_technologies` to see valid IDs |
+
+## Development
+
+```bash
+cd packages/mcp-server
+bun install
+bun run build
+bun run dev      # Watch mode
+bun test         # Run tests
+```
+
+## Links
+
+- **Website**: [stacksfinder.com](https://stacksfinder.com)
+- **Pricing**: [stacksfinder.com/pricing](https://stacksfinder.com/pricing)
+- **GitHub**: [github.com/hoklims/stacksmith](https://github.com/hoklims/stacksmith)
+- **npm**: [@stacksfinder/mcp-server](https://www.npmjs.com/package/@stacksfinder/mcp-server)
+
+## License
+
+MIT

package/dist/data/compatibility_matrix.json

@@ -0,0 +1,230 @@
+{
+	"$version": "1.1.0",
+	"$description": "Compatibility scores between technologies (0-100). 0 = hard incompatible, <50 = poor, 50-79 = acceptable, 80+ = good. Payments providers are mutually exclusive.",
+	"matrix": {
+		"react": {
+			"nextjs": 100,
+			"remix": 100,
+			"nuxt": 0,
+			"sveltekit": 0,
+			"drizzle": 95,
+			"prisma": 95
+		},
+		"vue": {
+			"nuxt": 100,
+			"nextjs": 0,
+			"remix": 0,
+			"sveltekit": 0,
+			"drizzle": 90,
+			"prisma": 95
+		},
+		"svelte": {
+			"sveltekit": 100,
+			"nextjs": 0,
+			"remix": 0,
+			"nuxt": 0,
+			"drizzle": 95,
+			"prisma": 90
+		},
+		"solid": {
+			"nextjs": 0,
+			"remix": 0,
+			"nuxt": 0,
+			"sveltekit": 0,
+			"drizzle": 85,
+			"prisma": 85
+		},
+		"nextjs": {
+			"react": 100,
+			"vercel": 100,
+			"cloudflare": 80,
+			"railway": 90,
+			"postgres": 95,
+			"sqlite": 70,
+			"supabase": 95,
+			"drizzle": 95,
+			"prisma": 95,
+			"better-auth": 90,
+			"clerk": 100
+		},
+		"nuxt": {
+			"vue": 100,
+			"vercel": 95,
+			"cloudflare": 85,
+			"railway": 90,
+			"postgres": 95,
+			"sqlite": 80,
+			"supabase": 90,
+			"drizzle": 90,
+			"prisma": 95
+		},
+		"sveltekit": {
+			"svelte": 100,
+			"vercel": 95,
+			"cloudflare": 90,
+			"railway": 90,
+			"postgres": 95,
+			"sqlite": 85,
+			"supabase": 90,
+			"drizzle": 100,
+			"prisma": 85,
+			"better-auth": 95
+		},
+		"remix": {
+			"react": 100,
+			"vercel": 90,
+			"cloudflare": 95,
+			"railway": 90,
+			"postgres": 95,
+			"sqlite": 85,
+			"supabase": 90,
+			"drizzle": 95,
+			"prisma": 90
+		},
+		"nodejs": {
+			"postgres": 95,
+			"sqlite": 90,
+			"supabase": 90,
+			"drizzle": 95,
+			"prisma": 95,
+			"vercel": 90,
+			"cloudflare": 75,
+			"railway": 95
+		},
+		"bun": {
+			"postgres": 90,
+			"sqlite": 95,
+			"supabase": 85,
+			"drizzle": 100,
+			"prisma": 70,
+			"vercel": 80,
+			"cloudflare": 85,
+			"railway": 90,
+			"sveltekit": 100
+		},
+		"postgres": {
+			"drizzle": 100,
+			"prisma": 100,
+			"supabase": 100,
+			"vercel": 95,
+			"cloudflare": 90,
+			"railway": 100
+		},
+		"sqlite": {
+			"drizzle": 100,
+			"prisma": 95,
+			"vercel": 60,
+			"cloudflare": 95,
+			"railway": 80
+		},
+		"supabase": {
+			"drizzle": 90,
+			"prisma": 95,
+			"postgres": 100,
+			"vercel": 95,
+			"cloudflare": 90,
+			"railway": 90,
+			"neon": 30
+		},
+		"neon": {
+			"drizzle": 98,
+			"prisma": 95,
+			"postgres": 100,
+			"vercel": 98,
+			"cloudflare": 85,
+			"railway": 90,
+			"sveltekit": 95,
+			"nextjs": 95,
+			"nuxt": 90,
+			"remix": 90,
+			"supabase": 30,
+			"sqlite": 20
+		},
+		"drizzle": {
+			"postgres": 100,
+			"sqlite": 100,
+			"supabase": 90,
+			"neon": 98,
+			"bun": 100,
+			"nodejs": 95
+		},
+		"prisma": {
+			"postgres": 100,
+			"sqlite": 95,
+			"supabase": 95,
+			"neon": 95,
+			"bun": 70,
+			"nodejs": 100
+		},
+		"vercel": {
+			"nextjs": 100,
+			"nuxt": 95,
+			"sveltekit": 95,
+			"remix": 90,
+			"postgres": 95,
+			"supabase": 95,
+			"neon": 98
+		},
+		"cloudflare": {
+			"nextjs": 80,
+			"nuxt": 85,
+			"sveltekit": 90,
+			"remix": 95,
+			"sqlite": 95,
+			"postgres": 85
+		},
+		"railway": {
+			"nextjs": 90,
+			"nuxt": 90,
+			"sveltekit": 90,
+			"remix": 90,
+			"postgres": 100,
+			"nodejs": 100,
+			"bun": 95
+		},
+		"stripe": {
+			"nextjs": 95,
+			"sveltekit": 90,
+			"nuxt": 90,
+			"remix": 90,
+			"nodejs": 95,
+			"bun": 90,
+			"paddle": 0,
+			"lemonsqueezy": 0,
+			"gumroad": 0
+		},
+		"paddle": {
+			"nextjs": 90,
+			"sveltekit": 95,
+			"nuxt": 90,
+			"remix": 88,
+			"nodejs": 90,
+			"bun": 90,
+			"stripe": 0,
+			"lemonsqueezy": 0,
+			"gumroad": 0
+		},
+		"lemonsqueezy": {
+			"nextjs": 85,
+			"sveltekit": 85,
+			"nuxt": 85,
+			"remix": 85,
+			"nodejs": 85,
+			"bun": 85,
+			"stripe": 0,
+			"paddle": 0,
+			"gumroad": 0
+		},
+		"gumroad": {
+			"nextjs": 70,
+			"sveltekit": 70,
+			"nuxt": 70,
+			"remix": 70,
+			"nodejs": 70,
+			"bun": 70,
+			"stripe": 0,
+			"paddle": 0,
+			"lemonsqueezy": 0
+		}
+	}
+}

package/dist/data/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Data version - update when syncing from source.
+ */
+export declare const DATA_VERSION = "2025.12.30";
+/**
+ * Score dimensions.
+ */
+export declare const SCORE_DIMENSIONS: readonly ["perf", "dx", "ecosystem", "maintain", "cost", "compliance"];
+export type ScoreDimension = (typeof SCORE_DIMENSIONS)[number];
+/**
+ * Human-readable dimension names.
+ */
+export declare const DIMENSION_LABELS: Record<ScoreDimension, string>;
+/**
+ * Technology categories.
+ */
+export declare const CATEGORIES: readonly ["frontend", "backend", "meta-framework", "database", "orm", "auth", "hosting", "payments"];
+export type Category = (typeof CATEGORIES)[number];
+/**
+ * Score contexts.
+ */
+export declare const CONTEXTS: readonly ["default", "mvp", "enterprise"];
+export type Context = (typeof CONTEXTS)[number];
+/**
+ * Score set for a technology.
+ */
+export interface Scores {
+    perf: number;
+    dx: number;
+    ecosystem: number;
+    maintain: number;
+    cost: number;
+    compliance: number;
+}
+/**
+ * Technology information.
+ */
+export interface TechInfo {
+    id: string;
+    name: string;
+    category: Category;
+    url: string;
+    scores: Record<Context, Scores>;
+}
+/**
+ * Get all technology IDs.
+ */
+export declare function getAllTechIds(): string[];
+/**
+ * Get a technology by ID.
+ */
+export declare function getTechnology(id: string): TechInfo | null;
+/**
+ * Get all technologies.
+ */
+export declare function getAllTechnologies(): TechInfo[];
+/**
+ * Get technologies by category.
+ */
+export declare function getTechnologiesByCategory(category: Category): TechInfo[];
+/**
+ * Get technologies grouped by category.
+ */
+export declare function getTechnologiesGroupedByCategory(): Record<Category, TechInfo[]>;
+/**
+ * Get scores for a technology in a specific context.
+ */
+export declare function getScores(techId: string, context?: Context): Scores | null;
+/**
+ * Calculate overall score (average of all dimensions).
+ */
+export declare function calculateOverallScore(scores: Scores): number;
+/**
+ * Get letter grade from score.
+ */
+export declare function scoreToGrade(score: number): string;
+/**
+ * Get compatibility score between two technologies.
+ * Returns 50 (neutral) if no direct compatibility is defined.
+ */
+export declare function getCompatibility(techA: string, techB: string): number;
+/**
+ * Get compatibility verdict.
+ */
+export declare function getCompatibilityVerdict(score: number): string;
+/**
+ * Find compatible technologies for a given tech.
+ * Returns sorted by compatibility score (descending).
+ */
+export declare function findCompatibleTechs(techId: string, limit?: number): Array<{
+    id: string;
+    score: number;
+}>;
+/**
+ * Find similar technology IDs using Levenshtein distance.
+ */
+export declare function findSimilarTechIds(input: string, limit?: number): string[];
+/**
+ * Check if a technology ID exists.
+ */
+export declare function techExists(id: string): boolean;
+/**
+ * Get source data version from JSON files.
+ */
+export declare function getSourceDataVersion(): {
+    scores: string;
+    compatibility: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,eAAO,MAAM,YAAY,eAAe,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,gBAAgB,wEAAyE,CAAC;AACvG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAO3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,sGASb,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,QAAQ,2CAA4C,CAAC;AAClE,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAChC;AAoBD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,EAAE,CAE/C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAExE;AAED;;GAEG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAmB/E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,OAAmB,GAAG,MAAM,GAAG,IAAI,CAIrF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAclD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAcrE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAWnG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAErE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAKhF"}