@iblai/mcp 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# IBL Frontend MCP Server
+
+An MCP (Model Context Protocol) server that provides comprehensive documentation and guidance for working with the IBL frontend packages.
+
+## Overview
+
+This MCP server helps AI assistants understand and work with:
+
+- **@iblai/web-containers**: Shared React components built on Radix UI
+- **@iblai/web-utils**: Authentication utilities, context providers, and hooks
+- **@iblai/data-layer**: Redux store and RTK Query APIs
+
+## Installation
+
+```bash
+cd packages/mcp-server
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+```bash
+# 1. Build the MCP server
+cd packages/mcp-server
+pnpm build
+
+# 2. Restart Claude Code (exit and re-enter your session)
+# The server is already configured in .claude/settings.json
+```
+
+That's it! Claude will now have access to IBL-specific tools and documentation.
+
+## Configuration
+
+The MCP server is pre-configured in `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "ibl-web-frontend": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["packages/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+No additional setup required - just build and restart Claude Code.
+
+## Project Structure
+
+```
+packages/mcp-server/
+├── src/
+│   ├── index.ts              # Main server entry point
+│   ├── resources/            # Documentation resources
+│   │   ├── index.ts          # Resource exports
+│   │   ├── packages-overview.ts
+│   │   ├── web-containers.ts
+│   │   ├── web-utils.ts
+│   │   ├── data-layer.ts
+│   │   ├── guides-layout.ts
+│   │   ├── guides-rbac.ts
+│   │   └── guides-theme.ts
+│   └── tools/                # MCP tools
+│       ├── index.ts          # Tool exports
+│       ├── component-info.ts
+│       ├── hook-info.ts
+│       ├── provider-setup.ts
+│       ├── api-query-info.ts
+│       └── page-template.ts
+└── dist/                     # Compiled output
+```
+
+## Available Resources
+
+The server provides the following 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://guides/layout` | Layout rules and patterns |
+| `ibl://guides/rbac` | RBAC (Role-Based Access Control) patterns |
+| `ibl://guides/theme` | Theme configuration |
+
+## Available Tools
+
+### get_component_info
+
+Get detailed information about a UI component.
+
+```
+Component name: Button, Card, Dialog, Profile, NotificationDropdown, Input, Select, Tabs, etc.
+```
+
+### get_hook_info
+
+Get detailed information about a React hook.
+
+```
+Hook name: useAdvancedChat, useMentorSettings, useGetMentorsQuery, useTenantMetadata, etc.
+```
+
+### get_provider_setup
+
+Get the correct provider setup for an app type.
+
+```
+App type: mentor, skills, auth, custom
+Features: chat, analytics, notifications, rbac
+```
+
+### get_api_query_info
+
+Get information about an RTK Query API endpoint.
+
+```
+Query name: useGetMentorsQuery, useGetUserMetadataQuery, usePlatformUserGroupsQuery, etc.
+```
+
+### create_page_template
+
+Generate a template for a new page following IBL patterns.
+
+```
+Page name: Dashboard, Settings, etc.
+Features: auth-required, rbac, analytics, sidebar, data-fetching
+App type: mentor, skills
+```
+
+## Development
+
+```bash
+# Watch mode
+pnpm dev
+
+# Build
+pnpm build
+
+# Run server directly
+pnpm start
+```
+
+## Key Concepts
+
+### Provider Hierarchy
+
+Apps must use providers in this order:
+
+**Skills App:**
+```
+StoreProvider → AuthProvider → TenantProvider → ClientLayout
+```
+
+**Mentor App:**
+```
+StoreProvider → AuthProvider → TenantProvider → MentorProvider → AppProvider
+```
+
+### Package Imports
+
+```typescript
+// Data Layer
+import { useGetMentorsQuery, mentorReducer } from '@iblai/data-layer';
+
+// Web Containers
+import { Button, Card, Dialog } from '@iblai/web-containers';
+
+// Web Utils
+import { AuthProvider, useAdvancedChat } from '@iblai/web-utils';
+```
+
+### RBAC Pattern
+
+```typescript
+import { WithPermissions } from '@/hoc/withPermissions';
+
+<WithPermissions rbacResource={`/platforms/${tenant}/#can_view_analytics`}>
+  {({ hasPermission }) => hasPermission && <AnalyticsButton />}
+</WithPermissions>
+```
+
+## Adding New Resources
+
+1. Create a new file in `src/resources/` (e.g., `my-resource.ts`)
+2. Export the resource object with `uri`, `name`, `description`, `mimeType`, and `content`
+3. Import and add it to `src/resources/index.ts`
+
+## Adding New Tools
+
+1. Create a new file in `src/tools/` (e.g., `my-tool.ts`)
+2. Export the tool definition and handler function
+3. Import and add it to `src/tools/index.ts`
+4. Add the case handler in `src/index.ts`

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+// Import resources
+import { RESOURCES } from './resources/index.js';
+// Import tools
+import { TOOLS, getComponentInfo, getHookInfo, getProviderSetup, getApiQueryInfo, createPageTemplate, } from './tools/index.js';
+// ============================================================================
+// IBL FRONTEND MCP SERVER
+// ============================================================================
+// This MCP server provides comprehensive documentation and guidance for
+// working with the IBL frontend packages: web-containers, web-utils, data-layer
+// ============================================================================
+const server = new Server({
+    name: 'ibl-frontend-mcp',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+// ============================================================================
+// RESOURCE HANDLERS
+// ============================================================================
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: Object.entries(RESOURCES).map(([uri, resource]) => ({
+            uri,
+            name: resource.name,
+            description: resource.description,
+            mimeType: resource.mimeType,
+        })),
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const resource = RESOURCES[uri];
+    if (!resource) {
+        throw new Error(`Resource not found: ${uri}`);
+    }
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: resource.mimeType,
+                text: resource.content,
+            },
+        ],
+    };
+});
+// ============================================================================
+// TOOL HANDLERS
+// ============================================================================
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case 'get_component_info': {
+            const componentName = args.componentName;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: getComponentInfo(componentName),
+                    },
+                ],
+            };
+        }
+        case 'get_hook_info': {
+            const hookName = args.hookName;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: getHookInfo(hookName),
+                    },
+                ],
+            };
+        }
+        case 'get_provider_setup': {
+            const { appType, features } = args;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: getProviderSetup(appType, features || []),
+                    },
+                ],
+            };
+        }
+        case 'get_api_query_info': {
+            const queryName = args.queryName;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: getApiQueryInfo(queryName),
+                    },
+                ],
+            };
+        }
+        case 'create_page_template': {
+            const { pageName, features, appType } = args;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: createPageTemplate(pageName, appType, features || []),
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// ============================================================================
+// SERVER STARTUP
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('IBL Frontend MCP Server running on stdio');
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/resources/data-layer.d.ts

@@ -0,0 +1,8 @@
+export declare const dataLayer: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    content: string;
+};
+//# sourceMappingURL=data-layer.d.ts.map

package/dist/resources/data-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-layer.d.ts","sourceRoot":"","sources":["../../src/resources/data-layer.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;CAmLrB,CAAC"}

package/dist/resources/data-layer.js

@@ -0,0 +1,181 @@
+export const dataLayer = {
+    uri: 'ibl://packages/data-layer',
+    name: 'Data Layer Package',
+    description: 'Redux store and RTK Query APIs',
+    mimeType: 'text/markdown',
+    content: `# @iblai/data-layer
+
+Redux Toolkit state management with RTK Query for API interactions.
+
+## Store Setup
+
+\`\`\`typescript
+import { configureStore } from '@reduxjs/toolkit';
+import { mentorReducer, mentorMiddleware } from '@iblai/data-layer';
+// or
+import { skillsReducer, skillsMiddleware } from '@iblai/data-layer';
+
+export const store = configureStore({
+  reducer: {
+    ...mentorReducer,    // Includes all RTK Query reducers
+    // your custom reducers
+    rbac: rbacReducer,
+    modals: modalsReducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(...mentorMiddleware),
+});
+\`\`\`
+
+## API Slices Overview
+
+The data-layer provides 37+ RTK Query API slices:
+
+### Mentor Management
+\`\`\`typescript
+import {
+  useGetMentorsQuery,
+  useGetMentorDetailsQuery,
+  useGetMentorSettingsQuery,
+  useCreateMentorMutation,
+  useEditMentorMutation,
+  useDeleteMentorMutation,
+  useForkMentorMutation,
+  useUpdateMentorVisibilityStatusMutation,
+} from '@iblai/data-layer';
+
+// Get all mentors for a tenant
+const { data: mentors } = useGetMentorsQuery({ org: tenantKey });
+
+// Get mentor settings
+const { data: settings } = useGetMentorSettingsQuery({
+  org: tenantKey,
+  mentorId,
+  username,
+});
+\`\`\`
+
+### User Management
+\`\`\`typescript
+import {
+  useGetUserMetadataQuery,
+  useUpdateUserMetadataMutation,
+  useUpdateUserAccountMutation,
+} from '@iblai/data-layer';
+
+const { data: user } = useGetUserMetadataQuery({
+  params: { username },
+});
+\`\`\`
+
+### Platform Administration
+\`\`\`typescript
+import {
+  useGetPlatformUsersQuery,
+  useGetPlatformUserGroupsQuery,
+  useGetPlatformUserGroupDetailsQuery,
+  useInviteUserMutation,
+  useUpdatePlatformUserRoleWithPoliciesMutation,
+} from '@iblai/data-layer';
+
+// Get users with pagination
+const { data: users } = useGetPlatformUsersQuery({
+  platformKey: tenantKey,
+  page: 1,
+  pageSize: 25,
+});
+\`\`\`
+
+### Tenant Management
+\`\`\`typescript
+import {
+  useGetTenantMetadataQuery,
+  useUpdateTenantMetadataMutation,
+  useGetUserTenantsQuery,
+} from '@iblai/data-layer';
+
+const { data: metadata } = useGetTenantMetadataQuery({ org: tenantKey });
+\`\`\`
+
+### Chat & Messages
+\`\`\`typescript
+import {
+  useGetPinnedMessagesQuery,
+  useGetRecentMessageQuery,
+  useUpdateMessageFeedbackMutation,
+} from '@iblai/data-layer';
+\`\`\`
+
+### Skills & Catalog
+\`\`\`typescript
+import {
+  useGetReportedSkillsQuery,
+  useGetDesiredSkillsQuery,
+  useGetCatalogSearchQuery,
+  useGetPersonalizedSearchQuery,
+} from '@iblai/data-layer';
+\`\`\`
+
+### MCP (Model Context Protocol)
+\`\`\`typescript
+import {
+  useGetMCPServersQuery,
+  useCreateMCPServerMutation,
+  useGetConnectedServicesQuery,
+  useStartOAuthFlowMutation,
+} from '@iblai/data-layer';
+\`\`\`
+
+### Analytics
+\`\`\`typescript
+import {
+  useGetAnalyticsOverviewQuery,
+  useGetAnalyticsUsersQuery,
+  useGetAnalyticsReportsQuery,
+} from '@iblai/data-layer';
+\`\`\`
+
+## Cache Tags
+
+RTK Query uses tags for cache invalidation:
+
+\`\`\`typescript
+// After creating a mentor, related queries are invalidated
+const [createMentor] = useCreateMentorMutation();
+await createMentor(data);
+// Queries with 'mentors' tag automatically refetch
+
+// Manual invalidation
+dispatch(mentorApi.util.invalidateTags(['mentors']));
+\`\`\`
+
+## Lazy Queries
+
+For conditional/on-demand data fetching:
+
+\`\`\`typescript
+import { useLazyGetMentorDetailsQuery } from '@iblai/data-layer';
+
+const [trigger, { data, isLoading }] = useLazyGetMentorDetailsQuery();
+
+// Trigger when needed
+useEffect(() => {
+  if (mentorId) {
+    trigger({ org: tenantKey, mentorId });
+  }
+}, [mentorId]);
+\`\`\`
+
+## Initialization
+
+\`\`\`typescript
+import { initializeDataLayer } from '@iblai/data-layer';
+
+// In your app initialization
+initializeDataLayer({
+  storageService: localStorage, // or AsyncStorage for React Native
+});
+\`\`\`
+`,
+};
+//# sourceMappingURL=data-layer.js.map

package/dist/resources/data-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-layer.js","sourceRoot":"","sources":["../../src/resources/data-layer.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,EAAE,2BAA2B;IAChC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE,gCAAgC;IAC7C,QAAQ,EAAE,eAAe;IACzB,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6KV;CACA,CAAC"}

package/dist/resources/guides-layout.d.ts

@@ -0,0 +1,8 @@
+export declare const guidesLayout: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    content: string;
+};
+//# sourceMappingURL=guides-layout.d.ts.map

package/dist/resources/guides-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guides-layout.d.ts","sourceRoot":"","sources":["../../src/resources/guides-layout.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;CAyOxB,CAAC"}