Dune Library MCP Server

Model Context Protocol (MCP) server providing AI agents access to the Dune Library knowledge base and component library.

Features

• Knowledge Base Search: Fuzzy search across curated learnings
• Component Library: Reusable React components with tests and documentation
• Auto Git-Sync: Automatic sync with GitHub repository
• Smart Context: Folder README context automatically included
• Contribution System: Propose new learnings and components via GitHub PRs

Installation

cd mcp-server
npm install
npm run build

Prerequisites for Contribution Features

To use propose_learning and propose_component tools:

1. Cursor CLI (cursor-agent)

Required for AI-powered analysis of proposals.

# Install Cursor CLI
curl https://cursor.com/install -fsS | bash

# Verify installation
cursor-agent --version

2. GitHub CLI (gh)

Required for creating pull requests. Uses your existing GitHub login.

# macOS
brew install gh

# Linux
# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md

# Authenticate
gh auth login

Configuration

Environment variables:

# Optional: Custom repository
DUNE_LIBRARY_REPO_URL=https://github.com/your-org/your-repo.git
DUNE_LIBRARY_BRANCH=master

# Optional: Custom cache directory
DUNE_LIBRARY_CACHE_DIR=/path/to/cache

# Optional: Local development mode (skip git sync)
DUNE_LIBRARY_LOCAL_MODE=true

Available Tools

Learning Tools

search_learnings

Search the knowledge base by keywords.

{
  "name": "search_learnings",
  "arguments": {
    "phrases": ["authentication", "oauth"],
    "limit": 5
  }
}

get_learning

Get a specific learning by path or browse a folder.

{
  "name": "get_learning",
  "arguments": {
    "path": "react/create-cdf-query-hook-factory.md"
  }
}

propose_learning

Propose a new learning or amendment. Creates a GitHub PR automatically.

{
  "name": "propose_learning",
  "arguments": {
    "content": "# Learning Title\n\n**Status**: ✅ Verified\n...",
    "rationale": "Needed to document best practice for X",
    "category": "react"
  }
}

Component Tools

search_components

Search the component library by keywords.

{
  "name": "search_components",
  "arguments": {
    "phrases": ["kanban", "drag-drop"],
    "limit": 5
  }
}

Response:

{
  "results": [{
    "name": "kanban-column",
    "path": "components/kanban-column",
    "description": "A drag-and-drop kanban column with reorderable cards",
    "files": ["README.md", "kanban-column.tsx", "kanban-column.test.tsx", "types.ts"],
    "keywords": ["kanban", "drag-drop", "sortable", "cards"],
    "dependencies": ["@dnd-kit/[email protected]", "@dnd-kit/[email protected]"]
  }],
  "query": "kanban drag-drop",
  "total": 1
}

get_component

Get a component directory (all files) or a specific file.

Get entire component:

{
  "name": "get_component",
  "arguments": {
    "path": "kanban-column",
    "include": "all"
  }
}

Get specific file:

{
  "name": "get_component",
  "arguments": {
    "path": "kanban-column/kanban-column.tsx"
  }
}

Filter by file type:

{
  "name": "get_component",
  "arguments": {
    "path": "kanban-column",
    "include": "code"  // "all" | "readme" | "code" | "tests"
  }
}

propose_component

Propose a new component or amendment. The system will:

1. Analyze your proposal against existing components
2. Generate required files (README, tests, types) if missing
3. Validate against component requirements
4. Create a GitHub PR with all files

New component:

{
  "name": "propose_component",
  "arguments": {
    "content": "// TypeScript component code...",
    "rationale": "Needed for sortable table functionality"
  }
}

Amendment to existing:

{
  "name": "propose_component",
  "arguments": {
    "content": "// Modified code...",
    "rationale": "Add keyboard navigation support",
    "targetComponent": "kanban-column",
    "targetFile": "kanban-column.tsx"
  }
}

Component Structure

Each component is a self-contained directory:

components/
├── README.md                    # Library documentation
├── kanban-column/               # Component directory
│   ├── README.md                # REQUIRED: API docs & examples
│   ├── kanban-column.tsx        # REQUIRED: Main implementation
│   ├── kanban-column.test.tsx   # REQUIRED: Unit tests
│   ├── types.ts                 # Optional: Shared types
│   └── styles.ts                # Optional: Separated styles

Component Requirements

1. README.md - Full documentation with:

   • Description and keywords
   • Installation/dependencies
   • API reference (props table)
   • Usage examples
   • Accessibility notes

2. Component file - Implementation with:

   • TypeScript types for all props
   • JSDoc documentation
   • Dependency injection (services passed as props)
   • Self-contained styles

3. Test file - Unit tests with:

   • Tests for all props and variants
   • Edge case coverage
   • Mocked dependencies

Available Resources

• learnings://cache - All cached learning metadata
• components://cache - All cached component directories
• learnings://diagnostics - Server status and statistics

Prompts

• dune-library-rules - Instructions for using the knowledge base

Development

# Build
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Testing

# Run all tests
npm test

# Run specific test suite
npm test -- unit/
npm test -- integration/
npm test -- e2e/

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "dune-library": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "DUNE_LIBRARY_LOCAL_MODE": "true"
      }
    }
  }
}

Documentation

• TESTING.md - Comprehensive testing guidelines
• CONTRIBUTING.md - Development workflow and code standards
• CHANGELOG.md - Version history and release notes