MCP Server

The Makerkit MCP Server provides AI agents with context-aware tools for working with the codebase.

The Makerkit MCP Server helps AI Agents code with the codebase by providing a set of tools for discovering UI components, running scripts, and managing Product Requirements Documents (PRDs).

Setup

The MCP Server is already configured in the .mcp.json file - but before being able to run it, we need to build it with the following command:

pnpm --filter "@kit/mcp-server" build

AI Agents should pick it up right away, but if they don't, make sure to add them manually using the same format as .mcp.json:

{
  "mcpServers": {
    "makerkit": {
      "type": "stdio",
      "command": "node",
      "args": ["tooling/mcp-server/build/index.js"]
    }
  }
}

Available Tools

The MCP Server provides three categories of tools:

UI Components Tools

Tools for discovering and inspecting the @kit/ui component library.

  • get_components - Lists all available UI components with their category (shadcn/makerkit/utils) and descriptions
  • get_component_content - Retrieves the full source code of a specific component
  • components_search - Searches components by keyword in name, description, or category
  • get_component_props - Extracts props, interfaces, and CVA variants from a component

Example usage by AI agents:

  • List all components → get_components()
  • Search for table-related components → components_search({ query: "table" })
  • Get the Button component source → get_component_content({ componentName: "button" })
  • Inspect Alert component props → get_component_props({ componentName: "alert" })

Scripts Tools

Tools for understanding available npm/pnpm scripts and their purpose.

  • get_scripts - Lists all scripts sorted by importance with usage guidance
  • get_script_details - Gets detailed info about a specific script including category and importance
  • get_healthcheck_scripts - Returns critical scripts that must run after writing code

Healthcheck scripts are marked as critical and should be run after any code changes:

  • typecheck - TypeScript type checking
  • lint / lint:fix - ESLint code quality checks
  • format:fix - Prettier code formatting
  • test - Unit test execution

PRD Management Tools

Tools for creating and managing Product Requirements Documents following ChatPRD best practices. PRDs are stored as JSON files in the .prds directory.

  • list_prds - Lists all PRD files in the .prds folder
  • get_prd - Retrieves the contents of a specific PRD file
  • create_prd - Creates a new structured PRD with title, problem statement, solution, and metrics
  • add_user_story - Adds a user story to an existing PRD with acceptance criteria
  • update_story_status - Updates a story's status (not_started, research, in_progress, review, completed, blocked)
  • export_prd_markdown - Exports the PRD as a formatted markdown file for sharing
  • get_implementation_prompts - Generates implementation prompts from user stories
  • get_improvement_suggestions - Provides suggestions to improve the PRD
  • get_project_status - Returns progress overview, next steps, and blockers

User Story Workflow:

  1. Create a PRD with create_prd
  2. Add user stories with add_user_story
  3. Track progress with update_story_status
  4. Generate implementation tasks with get_implementation_prompts
  5. Monitor progress with get_project_status

Configuration for AI Tools

Claude Code / Claude Desktop

The .mcp.json file in the project root is automatically detected. Ensure the server is built before starting your AI session.

Cursor

Add to your Cursor MCP settings:

{
  "makerkit": {
    "type": "stdio",
    "command": "node",
    "args": ["/absolute/path/to/project/tooling/mcp-server/build/index.js"]
  }
}

Windsurf

Configure in your Windsurf MCP settings with the same format, using absolute paths to the built server.

Rebuilding the Server

After modifying the MCP server source code in tooling/mcp-server/src, rebuild with:

pnpm --filter "@kit/mcp-server" build

Then restart your AI agent session to pick up the changes.

Why Use the MCP Server?

  • Component Discovery - AI agents can explore available UI components without reading multiple files
  • Consistent Patterns - Agents learn component APIs and variants directly from source
  • Script Guidance - Agents know which scripts to run and when
  • PRD Tracking - Maintain structured requirements that guide implementation
  • Reduced Hallucination - Real-time access to actual codebase information