taste-mcp

Production-grade MCP server for the taste-skill skill library.

Instead of manually pasting SKILL.md files into an LLM context, taste-mcp turns the repository into a structured MCP server with:

• Resources for skills, sections, guides, templates, and pattern vocabulary
• Prompts for design, redesign, image-generation, and Stitch workflows
• Tools for discovery, search, brief analysis, and compact context composition
• Modern MCP transport via Streamable HTTP
• Local stdio support for spawn-based MCP clients

What It Solves

The original taste-skill repo is a high-value prompt corpus, but it is optimized for manual or semi-manual loading:

• copy SKILL.md into chat
• install one skill at a time with npx skills add
• rely on the agent to discover the right markdown itself

taste-mcp removes that friction by indexing the repository once and exposing only the relevant parts to MCP clients on demand.

Features

• Indexes skills/*/SKILL.md into a normalized in-memory catalog
• Uses canonical skill IDs from frontmatter name, not folder names
• Resolves aliases from:
  • README.md
  • skills/llms.txt
  • skill.sh
• Splits large skills into section resources for targeted retrieval
• Extracts the taste-skill pattern vocabulary as searchable MCP resources
• Includes secondary guides:
  • CHANGELOG.md
  • research/**
  • .github/copilot-instructions.md
  • .claude-plugin/*.json
  • skills/stitch-skill/DESIGN.md
• Supports compact retrieval so clients do not receive the entire repository by default
• Ships with tests, Dockerfile, and CI workflow

MCP Surface

Resources

• catalog://skills
• catalog://guides
• catalog://patterns
• skill://<skill-id>
• skill://<skill-id>/section/<section-slug>
• pattern://<pattern-id>
• guide://<guide-id>

Prompts

• design-taste
• frontend-review
• landing-page-context
• image-generation-context
• stitch-design-system

Tools

• list_skills
• get_skill
• search_content
• recommend_skills
• review_brief
• compose_context
• list_patterns
• get_pattern

Project Structure

src/
  app/         config, logger, bootstrap
  bin/         http and stdio entrypoints
  content/     loader, indexer, search, retrieval
  domain/      shared domain types
  lib/         markdown and text helpers
  mcp/         MCP resource/tool/prompt registration
  transport/   Streamable HTTP transport wiring

test/
  indexer.test.ts
  retrieval.test.ts
  http.test.ts

Requirements

• Node.js 20.11+
• npm

Installation

npm install --no-package-lock

Development

Run the HTTP server in watch mode:

npm run dev:http

Run the stdio server in watch mode:

npm run dev:stdio

Build

npm run build

Test

npm test

Run

Streamable HTTP

npm run start:http

Default endpoints:

• MCP: http://127.0.0.1:3000/mcp
• Health: http://127.0.0.1:3000/healthz

stdio

npm run start:stdio

Environment Variables

Copy .env.example if needed.

Available configuration:

• REPOSITORY_ROOT
• MCP_HOST
• MCP_PORT
• MCP_ENDPOINT
• LOG_LEVEL
• MAX_CONTEXT_CHARS
• MAX_SEARCH_RESULTS
• SESSION_TTL_MS

Defaults are tuned for local use and deployment simplicity.

Example Tool Calls

Review a brief

{
  "brief": "Redesign my existing SaaS landing page without changing the stack. Keep it calm and premium.",
  "target": "auto"
}

Compose compact context

{
  "brief": "Create a premium 8-section fintech landing page with strong proof and restrained motion.",
  "target": "web-implementation",
  "maxChars": 12000,
  "includePatterns": true,
  "includeGuides": true,
  "includeChecklists": true
}

Recommend skills

{
  "brief": "Generate a 5-screen onboarding flow for a fitness app inside clean iPhone mockups.",
  "target": "auto"
}

Deployment

Docker

Build:

docker build -t taste-mcp .

Run:

docker run --rm -p 3000:3000 taste-mcp

GitHub Actions

CI is included at .github/workflows/ci.yml.

It runs:

• npm run build
• npm test

Design Notes

Why Streamable HTTP

This server uses modern MCP Streamable HTTP instead of legacy HTTP+SSE transport.

Reasons:

• it is the current recommended MCP transport for remote servers
• it supports the standard POST/GET/DELETE session model
• it works cleanly with modern MCP clients
• SSE remains available internally as part of Streamable HTTP where needed, without implementing the deprecated legacy transport

Why stable SDK v1

The implementation uses the latest stable production SDK:

• @modelcontextprotocol/sdk@^1.29.0

This keeps the server deployable today while still using Streamable HTTP and the current production MCP feature set.

Important Limitation

The original taste-skill repository defines a future block-library contract, but it does not yet ship an actual blocks/ corpus.

Because of that:

• taste-mcp exposes pattern vocabulary today
• it does not fake a get_block implementation for non-existent block files

Roadmap

• Semantic search with embeddings
• Vector retrieval for sections and patterns
• Persisted index snapshots for faster startup
• Optional auth for public HTTP deployments
• File watching / hot reload in development
• Multi-repository support
• Real block resources when the upstream repo adds concrete block files

Source Lineage

This project is built on top of the upstream content repository:

• Upstream corpus: Leonxlnx/taste-skill
• This repo: MCP packaging, indexing, retrieval, transport, tests, and deployment support

License

The original content repository is MIT-licensed. Review upstream licensing and attribution requirements if you publish derived distributions.