Content
# 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.
