kds-mcp

Model Context Protocol (MCP) server that provides component context from GitLab repositories. Fetches component structure, props, and Storybook usage examples directly from your private GitLab repository.

Features

• 🔍 Fetch component structure, props, and implementation details from GitLab
• 📚 Extract Storybook usage examples and component stories
• 📱 Support for both React and Flutter components
• 🚀 Built-in caching to minimize API calls during interactive sessions
• 🔐 Works with private GitLab repositories
• 🤖 Ready-to-use context bundles optimized for AI assistants

Installation

For End Users

Install globally via npm:

npm install -g kds-mcp

Or use directly with npx (no installation required):

npx -y kds-mcp

For Development

1. Clone the repository:

   git clone https://github.com/kevinananda/kds-mcp.git
   cd kds-mcp

2. Install dependencies:

   npm install

3. Add an .env file based on .env.example:

   cp .env.example .env

4. Run in development mode:

   npm run dev

Configuration

Environment Variables

Create a .env file or set environment variables with the following:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITLAB_TOKEN | ✅ | - | Personal access token with read_api scope | | GITLAB_PROJECT_ID | ✅ | - | Numeric ID or URL path of the target project | | GITLAB_BASE_URL | ❌ | https://gitlab.com | GitLab instance URL | | COMPONENT_ROOT | ❌ | src/components | Root directory for components | | STORY_ROOT | ❌ | src/stories | Root directory for Storybook stories | | MOBILE_COMPONENT_ROOT | ❌ | lib/components | Root directory for mobile components | | MOBILE_STORY_ROOT | ❌ | lib/stories | Root directory for mobile stories | | DEFAULT_REF | ❌ | main | Default Git branch or tag |

Claude Desktop Setup

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Using npx (recommended):

{
  "mcpServers": {
    "kds-mcp": {
      "command": "npx",
      "args": ["-y", "kds-mcp"],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token-here",
        "GITLAB_PROJECT_ID": "your-project-id",
        "GITLAB_BASE_URL": "https://gitlab.com",
        "COMPONENT_ROOT": "src/components",
        "STORY_ROOT": "src/stories"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "kds-mcp": {
      "command": "kds-mcp",
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token-here",
        "GITLAB_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Note: Restart Claude Desktop after updating the configuration.

Usage

Once configured, the following tools are available in Claude Desktop:

Tools

• list_components - List all available components (specify framework: "react" or framework: "flutter")
• get_component_context - Get component implementation and props (specify framework: "react" or framework: "flutter")
• get_component_usage_context - Get Storybook/Widgetbook usage examples (specify framework: "react" or framework: "flutter")

Example Queries

Ask Claude:

• "List all available React components"
• "Show me the Button component implementation for React"
• "Get usage examples for the Card component in Flutter"
• "Fetch the TextField component for Flutter"

Getting a GitLab Token

1. Go to your GitLab instance (e.g., gitlab.com)
2. Navigate to User Settings → Access Tokens
3. Create a new token with the read_api scope
4. Copy the token and add it to your configuration

Architecture

• src/server.ts – MCP server entry-point and tool declarations.
• src/component-bundle.ts – orchestration logic that combines GitLab data and parsing results.
• src/gitlab.ts – GitLab API wrapper with pagination and retry handling.
• src/parsers/* – Source and Storybook extraction helpers.
• src/cache.ts – Simple TTL cache used for component bundles and GitLab responses.
• src/config.ts – Environment configuration with runtime validation.

Next Steps

• Flesh out the component + story parsers for your codebase conventions.
• Add tests around parsing and API layers.
• Extend the MCP toolset (e.g. list_components) as needed.