# Cortex MCP

[![CI](https://github.com/BasharAmso/cortex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/BasharAmso/cortex-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/cortex-mcp-server)](https://www.npmjs.com/package/cortex-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A knowledge delivery engine that ships with a built-in library of 728 agents, skills, patterns, and examples across 26 domains — and serves them on-demand to any MCP-compatible AI tool.

Instead of every project loading its own framework files into context (wasting 90%+ of the token budget), Cortex MCP is installed once and feeds the right knowledge to any project that needs it.

## Setup

Two steps. Copy-paste each line into your terminal.

**Step 1 — Install it:**

```bash
npm install -g cortex-mcp-server
```

> Don't have Node.js? Download it from [nodejs.org](https://nodejs.org) (pick the LTS version). Then come back and run the line above.

**Step 2 — Connect it to your AI tool:**

<details>
<summary><strong>Claude Code</strong> (one command)</summary>

```bash
claude mcp add -s user cortex -- cortex-mcp-server
```

Restart Claude Code. Done.
</details>

<details>
<summary><strong>Cursor</strong></summary>

1. Open Cursor
2. Go to **Settings** (gear icon) > **MCP**
3. Click **Add new MCP server**
4. Name: `cortex` | Command: `cortex-mcp-server`

Or paste this into `~/.cursor/mcp.json` if you prefer:

```json
{
  "mcpServers": {
    "cortex": {
      "command": "cortex-mcp-server"
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf</strong></summary>

1. Open Windsurf
2. Go to **Settings** > **MCP Servers**
3. Add a new server with command: `cortex-mcp-server`
</details>

<details>
<summary><strong>Cline / Continue / Zed</strong></summary>

These tools support MCP via a JSON config file. Add Cortex to your MCP config:

```json
{
  "mcpServers": {
    "cortex": {
      "command": "cortex-mcp-server"
    }
  }
}
```

Check your tool's docs for the config file location.
</details>

<details>
<summary><strong>Any other MCP-compatible tool</strong></summary>

Cortex MCP uses stdio transport. Any tool that can launch an MCP server via command line works:

- **Command:** `cortex-mcp-server`
- **Transport:** stdio
- **No API keys or config required**

If your tool asks for a server URL instead of a command, it expects HTTP transport which Cortex doesn't support (by design — stdio is more secure).
</details>

**That's it.** Now just work normally. Your AI tool will pull knowledge from the library when it needs it. You can also ask directly:

- "Search for error handling patterns"
- "Find the authentication skill"
- "Show me how to set up Stripe payments"
- "What agents are available?"

## How It Works

```mermaid
flowchart TB
    User["You (any AI tool)"]

    subgraph Client["Your AI Tool (any MCP client)"]
        Bashi["Bashi (Standalone or Lite)"]
        Claude["Claude Code"]
        Cursor["Cursor"]
        Windsurf["Windsurf"]
        Others["Cline · Continue · Zed\nCopilot · Codex · any MCP client"]
    end

    MCP{"Cortex MCP\nconnected?"}

    subgraph Cortex["Cortex MCP — Knowledge Library"]
        Fragments["728 Fragments"]
        Pillars["26 Domain Pillars"]
    end

    NoMCP["Works without Cortex\n(no knowledge grounding)"]

    User --> Client
    Client --> MCP
    MCP -->|Yes| Cortex
    MCP -.->|No| NoMCP
    Fragments --- Pillars

    style Client fill:#e8f4fd,stroke:#2196f3,color:#000
    style Cortex fill:#e8f5e9,stroke:#4caf50,color:#000
    style MCP fill:#fff3e0,stroke:#ff9800,color:#000
    style NoMCP fill:#e0e0e0,stroke:#666,stroke-dasharray: 5 5,color:#000
```

Your AI tool calls `search_knowledge` and `get_fragment` via MCP. Cortex returns the right knowledge for the task. Your project repos stay lightweight.

**Fragments load on demand.** If you're building a game, Cortex only serves game-dev patterns when you ask for them. Salon booking examples never touch your context window unless you search for them. Use the `budget` parameter on `search_knowledge` to control how much context each search returns — the default keeps responses lean, increase it when you need deeper reference material.

For the full architecture, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

### What's inside

```
resources/
├── agents/      10 agent definitions
├── skills/     443 skill procedures
├── patterns/   225 reusable patterns
└── examples/    50 code examples
```

## For Skill Authors

Skills define **what to do**. Cortex provides **what to know**.

Any skill -- in Claude Code, Cursor, Copilot, or custom agents -- can call Cortex mid-execution to ground its output in validated patterns:

1. `search_knowledge("auth patterns", category="patterns")` -- find relevant knowledge
2. `get_fragment("PAT-0042")` -- pull the full pattern into context
3. Apply the pattern alongside the skill's own procedure

Your skills get smarter without getting longer. The knowledge stays in Cortex, versioned and searchable, instead of duplicated across every skill file.

Bashi v3.2.0 includes three reference implementations: backend-dev, security-audit, and ai-feature each have a `## Knowledge Enhancement (MCP mode)` section showing this pattern in practice.

## What's in the Library

| Category | Count | Examples |
|----------|-------|---------|
| **Agents** | 10 | Builder, Reviewer, Architect, Product Manager, Designer, Fixer, Deployer |
| **Skills** | 443 | CRM, Lead Scoring, Market Sizing, LinkedIn Strategy, Salon Booking, Restaurant POS, Code Review, Debugging, Game Physics, Level Design, E-Commerce, IoT, Healthcare, Finance, Education |
| **Patterns** | 225 | Error Handling, API Design, Circuit Breaker, Saga, Cart State, Checkout Recovery, Appointment Booking, POS Architecture, CRM Data Model, Inventory Tracking, Achievement System |
| **Examples** | 50 | Phaser Game, ECS, Product Catalog, Checkout, API Gateway, Circuit Breaker, MVP Landing Page, A/B Testing, CRM Pipeline, Salon Booking, Online Course, IoT Dashboard, Competitor Analysis, Prayer Times, Go Server, Web Scraper, Kanban Board, and more |

Every fragment includes synonyms for natural language matching. Ask "how do I add logins" and it finds the authentication pattern. Ask "my app is slow" and it finds the performance skill. Ask "how do I grow on LinkedIn" and it finds the LinkedIn strategy skill.

### 26 Knowledge Pillars

| Pillar | Fragments | What's Covered |
|--------|-----------|---------------|
| **Software Dev** | 78 | Error handling, APIs, testing, security, DevOps, CI/CD |
| **Framework Core** | 31 | Agents, orchestration, quality review, deployment |
| **Frontend** | 30 | React, state management, testing, performance, i18n, security |
| **UX Design** | 30 | Usability testing, design systems, accessibility, prototyping |
| **Architecture** | 30 | API gateways, message queues, caching, serverless, GraphQL |
| **App Polish** | 30 | Loading states, animations, keyboard shortcuts, feature flags |
| **E-Commerce** | 30 | Product catalogs, checkout, shipping, subscriptions, fraud prevention |
| **Game Dev** | 30 | Physics, audio, level design, multiplayer, procedural generation |
| **Education** | 30 | Course platforms, flashcards, grading, adaptive learning, AI tutoring |
| **Coding Literacy** | 30 | Reading code, code review, debugging, understanding abstractions |
| **Business Automation** | 30 | Salon booking, POS systems, invoicing, scheduling, loyalty programs |
| **Sales** | 30 | CRM, lead scoring, pipeline management, cold outreach, forecasting |
| **Market Research** | 30 | Competitor analysis, market sizing, surveys, trend analysis |
| **Personal Brand** | 30 | LinkedIn, newsletters, podcasting, speaking, community building |
| **Product Business** | 30 | MVP strategy, pricing, A/B testing, metrics, churn prevention |
| **Content Creation** | 30 | Writing, copywriting, YouTube, newsletters, AI-assisted creation |
| **Platform** | 30 | SwiftUI, Compose, Flutter, Vue, Svelte, Angular, Next.js |
| **Health** | 15 | Telehealth, FHIR, mental health apps, wearables, medication tracking |
| **Finance** | 15 | Personal finance, banking APIs, portfolios, tax engines, billing |
| **Collaboration** | 15 | Wikis, project management, video conferencing, team chat |
| **Religious** | 15 | Prayer times, scripture readers, donations, devotionals, sermons |
| **IoT** | 15 | Edge computing, MQTT, dashboards, smart home, industrial IoT |
| **Developer Growth** | 15 | Technical writing, open source, career growth, interview prep |
| **Language** | 15 | Java, C#, Swift, Kotlin, PHP, Ruby, concurrency patterns |
| **Automation** | 15 | Web scraping, browser automation, data pipelines, chatbots |
| **Domain-Specific** | 15 | Legal tech, construction, agriculture, logistics, event management |

## Features

- **728 built-in fragments** across 26 domains — agents, skills, patterns, and code examples
- **Pillar filtering** — filter by domain (e.g., `game-dev`, `ecommerce`, `sales`, `coding-literacy`)
- **Synonym matching** — finds fragments even when you use informal language
- **Three-tier search** — quick cache (~2ms), pre-built index (~5-10ms), fuzzy fallback (~15-20ms)
- **Token budgeting** — respects context limits with four output modes
- **Zero-result recovery** — suggests alternatives when nothing matches exactly
- **Stack detection** — `detect_project` tool identifies your stack and suggests relevant searches
- **Works with any MCP client** — Claude Code, Cursor, Windsurf, and others
- **Zero cost** — no cloud, no API keys, runs locally

## MCP Tools

| Tool | Description |
|------|-------------|
| `search_knowledge` | Natural language search with mode, budget, and category filters |
| `get_fragment` | Retrieve a fragment by ID with dependency and related notes |
| `browse_library` | Browse all fragments or filter by category |
| `list_categories` | List categories and fragment counts |
| `detect_project` | Detect your project's stack and get suggested searches |
| `search_metrics` | View diagnostic search metrics (tier rates, zero-results, top fragments) |

## Output Modes

| Mode | What you get | Use when |
|------|-------------|----------|
| `index` | IDs and names only | Quick overview |
| `minimal` | JSON metadata + URIs | Default — good balance |
| `catalog` | Full metadata, no content | Browsing before loading |
| `full` | Complete markdown content | Ready to use |

## Configuration (optional)

Create `cortex.config.json` in your project root if you want to customize:

```json
{
  "customDirectories": ["./my-knowledge"],
  "matching": {
    "maxResults": 10,
    "defaultMode": "minimal",
    "defaultBudget": 4000
  }
}
```

Defaults work out of the box. Most users don't need a config file.

## Writing Your Own Fragments

See [docs/FRAGMENT-AUTHORING-GUIDE.md](docs/FRAGMENT-AUTHORING-GUIDE.md) for the complete guide.

Quick version: create a markdown file with YAML frontmatter in any configured directory:

```yaml
---
id: SKL-CUSTOM-001
name: My Custom Skill
category: skills
tags: [my-tag, another-tag]
capabilities: [what-it-can-do]
useWhen:
  - when to use this skill
synonyms: ["informal way to ask for it", "another way to ask"]
estimatedTokens: 500
lastUpdated: "2026-03-29"
difficulty: intermediate
relatedFragments: []
dependencies: []
---

# My Custom Skill

Content here...
```

## Development

```bash
npm install         # Install dependencies
npm run dev         # Dev mode (hot reload)
npm run build       # Build
npm run build-index # Rebuild search indexes
npm test            # Run tests
npm run typecheck   # Type check
```

## Troubleshooting

**"command not found" after install?** Close and reopen your terminal. If it still doesn't work, try `npx cortex-mcp-server` instead.

**Not seeing results?** Restart your AI tool after adding the MCP config. Changes only take effect on restart.

**Wrong fragments returned?** Try broader search terms. Use `browse_library` to see everything available.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up locally, submit fragments, and open pull requests.

## About

Built by [Bashar Amso](https://github.com/BasharAmso). I got tired of loading the same framework files into every project and burning through my token budget before asking my first question. Cortex MCP fixes that.

Part of the [Bashi](https://github.com/BasharAmso/bashi) ecosystem.

## Acknowledgments

This library was built by researching patterns from hundreds of open-source projects, technical documentation, and community best practices. We're grateful to the open-source community whose shared knowledge made this possible.

## License

MIT