Reflection Skills MCP

🚀 Reflection Skills MCP

Reflection Skills MCP is an open - source Model Context Protocol (MCP) server. It offers a small, carefully - curated set of developer - native reflection frameworks, exercises, and prompt packs.

This server is designed for use by:

• Journaling and reflection apps (such as Jots)
• Coaching or mentoring agents
• Developer productivity tools
• Retrospective tooling
• Personal agent workflows

The server provides MCP tools that return structured, evidence - informed reflection guidance, which can be configured according to depth and context.

Note: Version 1 is deliberately limited to 10 high - leverage cards to maintain quality and coherence.

🚀 Quick Start

Just follow the steps in the "Running the MCP server locally (recommended)" and "Remote / hosted (optional)" sections to get started with the Reflection Skills MCP.

✨ Features

What this repo contains

This is a monorepo with four main aspects:

1. Schema: Shared JSON schemas and TypeScript types.
2. Dataset: Curated reflection “cards” + search index.
3. Server: MCP server exposing reflection tools.
4. Tooling: CLI, evals, examples, and CI.

The directory structure is as follows: reflection - skills - mcp/ ├─ docs/ # Canonical documentation ├─ packages/ │ ├─ schema/ # Schemas + TS types │ ├─ dataset/ # Cards + indexes │ ├─ server/ # MCP server (stdio / HTTP) │ ├─ cli/ # Local runner + utilities │ ├─ evals/ # Retrieval quality evals │ └─ examples/ # Client examples └─ .github/workflows/ # CI

What is a “card”?

A card is a small, structured unit of reflection knowledge, which can be:

• A framework (e.g., SBAR, tradeoff analysis).
• An exercise (e.g., 5 Whys).
• A prompt pack (e.g., daily pulse).

Each card has the following characteristics:

• It is short and actionable.
• It is written in developer language.
• It is tagged with a tiny, fixed tag set.
• It is licensed for reuse.

Developer - native tags (v1)

incident · decision · collaboration · shipping · learning · debugging

MCP tools exposed

The server provides the following MCP tools:

• reflection.search_cards: Search cards by query, tags, or type.
• reflection.get_card: Fetch a full card by id.
• reflection.recommend: Recommend cards based on signals (focus areas, use case) and config.
• reflection.daily_pulse: Generate a daily pulse message + a small prompt + suggested cards.

All tools:

• Accept partial config.
• Apply sensible defaults.
• Never require user - specific data.

See full details in [docs/tool - reference.md](docs/tool - reference.md).

Configuration model

All tools accept an optional ReflectionContextConfig object. You can control the following aspects:

• Depth (quick | standard | deep).
• Audience level (junior | mid | senior | staff_plus).
• Focus dimensions (clarity, tradeoffs, learning, etc.).
• Time budget.
• Output size.
• Use case (post - reflection, daily pulse, weekly review).

If no config is provided, safe defaults are applied. The schema is located at: packages/schema/json/ReflectionContextConfig.schema.json

📦 Installation

Running the MCP server locally (recommended)

Most MCP users run servers locally via stdio.

Remote / hosted (optional)

For production or remote access, the MCP server can also run over HTTP. A Dockerfile is included to support deployments on platforms.

Install & build

npm install
npm run build
node packages/server/build/index.js

Configure your MCP host (Claude Desktop, VS Code, etc.) to run:

{
  "command": "node",
  "args": ["ABSOLUTE_PATH/packages/server/build/index.js"]
}

No hosting is required. In production, you can use this MCP server as a remote MCP service over Streamable HTTP for example.

💻 Usage Examples

Basic Usage

To search for cards, you can use the reflection.search_cards tool. For example:

// Assume you have a proper MCP client setup
const result = await client.reflection.search_cards({ query: 'incident' });
console.log(result);

Advanced Usage

If you want to recommend cards based on specific focus areas and use cases, you can use the reflection.recommend tool:

const config = {
  focusAreas: ['learning', 'collaboration'],
  useCase: 'post - reflection'
};
const recommendedCards = await client.reflection.recommend(config);
console.log(recommendedCards);

📚 Documentation

Dataset (v1)

Version 1 contains exactly 10 cards, which are organized as follows:

• frameworks/
• exercises/
• prompt - packs/
• studies/ (reserved, empty in v1)

Cards are located under: packages/dataset/cards/v1/

Indexes are pre - computed in: packages/dataset/indexes/cards.index.json

See docs/dataset - guide.md and docs/card - authoring.md for more details.

Evals

The repo includes lightweight retrieval evals to prevent regressions.

• Inputs: packages/evals/cases/v1.jsonl
• Metrics: precision@k, recall@k

To run the evals, use the following command:

npm --prefix packages/evals run evals

See docs/evals.md for more information.

Potential use cases

Reflection Skills MCP is designed to be generic and reusable. Common use cases include:

• Journaling & reflection apps: Provide structured reflection guidance, daily pulses, and frameworks without building your own content engine.
• Coaching or mentoring agents: Power “supportive buddy”, “senior engineer”, or “lead” personas with consistent reflection frameworks.
• Developer productivity tools: Add post - PR, post - incident, or end - of - day reflection prompts to existing workflows.
• Retrospectives & team learning: Support lightweight retros, post - mortems, and decision reviews with shared language and structure.
• Personal agent workflows: Plug into local or remote agent setups as a reflection knowledge layer via MCP.

The MCP is stateless, open - source, and does not require access to user data, making it safe to integrate across many contexts.

What this repo is not

• ❌ A journaling app
• ❌ A personalization engine
• ❌ A therapy or mental health system
• ❌ A hosted SaaS

It is a portable reflection knowledge server.

Contributing

Contributions are welcome, but scoped intentionally. Please read:

• CONTRIBUTING.md
• docs/card - authoring.md

Propose v2 expansions via issues first.

📄 License

• Code is licensed under the MIT License.
• Reflection card content (frameworks, exercises, prompt packs) is licensed under CC BY 4.0.

Frameworks referenced in this repository are industry - standard methods. The original frameworks are not claimed as original works; only the curation, structure, and wording of the cards are licensed here.