# taste-mcp

Production-grade MCP server for the [`taste-skill`](https://github.com/Leonxlnx/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

```text
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

```bash
npm install --no-package-lock
```

## Development

Run the HTTP server in watch mode:

```bash
npm run dev:http
```

Run the stdio server in watch mode:

```bash
npm run dev:stdio
```

## Build

```bash
npm run build
```

## Test

```bash
npm test
```

## Run

### Streamable HTTP

```bash
npm run start:http
```

Default endpoints:

- MCP: `http://127.0.0.1:3000/mcp`
- Health: `http://127.0.0.1:3000/healthz`

### stdio

```bash
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

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

### Compose compact context

```json
{
  "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

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

## Deployment

### Docker

Build:

```bash
docker build -t taste-mcp .
```

Run:

```bash
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.