# @iblai/mcp

An MCP (Model Context Protocol) server that provides AI assistants with comprehensive documentation for the IBL frontend packages — components, hooks, API queries, provider setup patterns, and Playwright test helpers.

## Quick Start

### With Claude Code

```bash
# No install needed — just add and go
claude mcp add --transport stdio iblai-js-mcp -- npx @iblai/mcp
```

Or share with your team by creating `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "iblai-js-mcp": {
      "command": "npx",
      "args": ["@iblai/mcp"]
    }
  }
}
```

> **pnpm projects:** If your project uses pnpm and has `@iblai/iblai-js` installed (which depends on `@iblai/mcp`), `npx` may find the transitive dependency locally but fail to link its binary. Use `pnpm dlx` instead:
>
> ```bash
> claude mcp add --transport stdio iblai-js-mcp -- pnpm dlx @iblai/mcp
> ```
>
> Or in `.mcp.json`:
>
> ```json
> {
>   "mcpServers": {
>     "iblai-js-mcp": {
>       "command": "pnpm",
>       "args": ["dlx", "@iblai/mcp"]
>     }
>   }
> }
> ```

### With Other MCP Clients

The server uses stdio transport and follows the [MCP specification](https://modelcontextprotocol.io):

```bash
npx @iblai/mcp
# or in pnpm projects:
pnpm dlx @iblai/mcp
```

## What It Provides

### Tools

| Tool | Description |
| --- | --- |
| `get_component_info` | Detailed props, usage examples, and category for any UI component |
| `get_hook_info` | Parameters, return types, and examples for React hooks |
| `get_api_query_info` | RTK Query endpoint details and usage patterns |
| `get_provider_setup` | Correct provider hierarchy for each app type (mentor, skills, auth) |
| `create_page_template` | Generate new pages following IBL patterns |
| `get_playwright_helper_info` | E2E test helper documentation |

### Resources

| Resource URI | Description |
| --- | --- |
| `ibl://packages/overview` | Overview of all IBL frontend packages |
| `ibl://packages/web-containers` | UI components documentation |
| `ibl://packages/web-utils` | Providers and hooks documentation |
| `ibl://packages/data-layer` | Redux and RTK Query documentation |
| `ibl://packages/playwright` | Playwright test utilities documentation |
| `ibl://guides/layout` | Layout rules and patterns |
| `ibl://guides/rbac` | RBAC (Role-Based Access Control) patterns |
| `ibl://guides/theme` | Theme configuration |
| `ibl://guides/playwright` | E2E testing setup guide |

### Prompts

| Prompt | Description |
| --- | --- |
| `setup-new-app` | Step-by-step guide for setting up a new IBL app |
| `setup-e2e-testing` | Guide for setting up Playwright E2E tests |
| `create-playwright-test` | Template for writing a new Playwright test |

## Packages Covered

- **@iblai/web-containers** — Shared React components (Radix UI primitives, feature components)
- **@iblai/web-utils** — Authentication, context providers, chat hooks, utilities
- **@iblai/data-layer** — Redux store, RTK Query API slices
- **@iblai/iblai-js/playwright** — Playwright test helpers, auth setup, config generation

## Alternative Installation

If you install `@iblai/iblai-js` globally, the MCP server is available as a binary:

```bash
npm install -g @iblai/iblai-js
claude mcp add --transport stdio iblai-js-mcp -- ibl-mcp-server
```

## Development (Monorepo Contributors)

### Local Setup

```bash
cd packages/mcp-server
pnpm install
pnpm build
```

The server is pre-configured in `.mcp.json` at the repo root to use the local build.

### Validating Documentation Coverage

```bash
pnpm --filter=@iblai/mcp run validate:exports
```

This checks that MCP docs stay in sync with actual package exports. CI will fail on PRs that introduce drift. To allowlist intentionally undocumented exports, add them to `scripts/export-allowlist.json`.

### Project Structure

```
packages/mcp-server/
├── src/
│   ├── index.ts              # Server entry point (McpServer API)
│   ├── resources/            # Documentation resources
│   ├── tools/                # MCP tools (component-info, hook-info, etc.)
│   └── prompts/              # MCP prompts (setup guides, templates)
├── scripts/
│   ├── validate-exports.ts   # Export drift detection script
│   └── export-allowlist.json # Intentionally undocumented exports
└── dist/                     # Compiled output
```

### Adding Documentation

**New resource:** Create a file in `src/resources/`, export it from `src/resources/index.ts`, and register it in `src/index.ts`.

**New tool:** Create a file in `src/tools/`, export it from `src/tools/index.ts`, and register it in `src/index.ts`.

**New prompt:** Create a file in `src/prompts/`, export it from `src/prompts/index.ts`, and register it in `src/index.ts`.

## License

ISC