@contextos/mcp 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@contextos/mcp",
+    "version": "0.1.0",
+    "description": "Model Context Protocol server for ContextOS - enables AI tools to access optimized context",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "contextos-mcp": "./dist/index.js"
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format esm --clean",
+        "dev": "tsx watch src/index.ts",
+        "start": "node dist/index.js"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^0.5.0",
+        "@contextos/core": "workspace:*"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "tsx": "^4.7.0",
+        "typescript": "^5.4.0"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "ai",
+        "context",
+        "cursor",
+        "claude"
+    ],
+    "author": "ContextOS Team",
+    "license": "MIT"
+}

package/src/definitions.ts

@@ -0,0 +1,166 @@
+/**
+ * MCP Tool, Resource, and Prompt Definitions
+ * Defines all capabilities exposed by the ContextOS MCP server
+ */
+
+import type { Tool, Resource, Prompt } from '@modelcontextprotocol/sdk/types.js';
+
+// ═══════════════════════════════════════════════════════════
+// TOOLS - Actions that AI can perform
+// ═══════════════════════════════════════════════════════════
+
+export const TOOLS: Tool[] = [
+    {
+        name: 'contextos_build',
+        description: 'Build optimized context for a specific goal. Returns the most relevant files from the codebase based on semantic similarity, dependency graph, and custom rules.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goal: {
+                    type: 'string',
+                    description: 'The coding task or goal (e.g., "Add authentication to UserController")',
+                },
+            },
+            required: ['goal'],
+        },
+    },
+    {
+        name: 'contextos_analyze',
+        description: 'Perform deep analysis of the codebase using RLM engine. Can find patterns, security issues, or answer complex questions about the code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Analysis query (e.g., "Find potential security vulnerabilities")',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'contextos_find',
+        description: 'Find files matching a pattern in the indexed codebase.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'Glob pattern to match (e.g., "**/auth/**/*.ts")',
+                },
+            },
+            required: ['pattern'],
+        },
+    },
+    {
+        name: 'contextos_deps',
+        description: 'Get dependencies of a file up to a specified depth.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file: {
+                    type: 'string',
+                    description: 'File path to analyze dependencies for',
+                },
+                depth: {
+                    type: 'number',
+                    description: 'Maximum depth to traverse (default: 2)',
+                },
+            },
+            required: ['file'],
+        },
+    },
+    {
+        name: 'contextos_explain',
+        description: 'Get an AI-powered explanation of a file, including its purpose, key functions, and how it relates to other parts of the codebase.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file: {
+                    type: 'string',
+                    description: 'File path to explain',
+                },
+            },
+            required: ['file'],
+        },
+    },
+    {
+        name: 'contextos_status',
+        description: 'Get the current status of ContextOS: project info, index status, and configuration.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+];
+
+// ═══════════════════════════════════════════════════════════
+// RESOURCES - Data that AI can read
+// ═══════════════════════════════════════════════════════════
+
+export const RESOURCES: Resource[] = [
+    {
+        uri: 'contextos://context/current',
+        name: 'Current Context',
+        description: 'The most recently built context (output of ctx build/goal)',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'contextos://project/info',
+        name: 'Project Info',
+        description: 'Project configuration from context.yaml (name, language, framework, stack)',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'contextos://project/constraints',
+        name: 'Coding Constraints',
+        description: 'Project coding rules and constraints that should be followed',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'contextos://project/structure',
+        name: 'Project Structure',
+        description: 'Directory tree of the project (excluding node_modules, etc.)',
+        mimeType: 'text/plain',
+    },
+];
+
+// ═══════════════════════════════════════════════════════════
+// PROMPTS - Pre-built prompt templates
+// ═══════════════════════════════════════════════════════════
+
+export const PROMPTS: Prompt[] = [
+    {
+        name: 'code_with_context',
+        description: 'Start a coding task with optimized context from ContextOS',
+        arguments: [
+            {
+                name: 'goal',
+                description: 'The coding task or goal',
+                required: true,
+            },
+        ],
+    },
+    {
+        name: 'review_code',
+        description: 'Review a file and its dependencies',
+        arguments: [
+            {
+                name: 'file',
+                description: 'File path to review',
+                required: true,
+            },
+        ],
+    },
+    {
+        name: 'debug_issue',
+        description: 'Debug an issue with relevant context',
+        arguments: [
+            {
+                name: 'issue',
+                description: 'Description of the issue',
+                required: true,
+            },
+        ],
+    },
+];

package/src/index.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * ContextOS MCP Server
+ * 
+ * Model Context Protocol server that provides AI tools (Claude Code, Cursor, etc.)
+ * with optimized context from ContextOS.
+ * 
+ * Usage:
+ *   npx @contextos/mcp
+ *   
+ * Configure in Claude Desktop:
+ *   {
+ *     "mcpServers": {
+ *       "contextos": {
+ *         "command": "npx",
+ *         "args": ["@contextos/mcp"]
+ *       }
+ *     }
+ *   }
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+    ListResourcesRequestSchema,
+    ReadResourceRequestSchema,
+    ListPromptsRequestSchema,
+    GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { ContextOSProvider } from './provider.js';
+import { TOOLS, RESOURCES, PROMPTS } from './definitions.js';
+
+// Initialize server
+const server = new Server(
+    {
+        name: 'contextos',
+        version: '0.1.0',
+    },
+    {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    }
+);
+
+// Initialize ContextOS provider
+const provider = new ContextOSProvider();
+
+// ═══════════════════════════════════════════════════════════
+// TOOLS - Actions that AI can perform
+// ═══════════════════════════════════════════════════════════
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+        switch (name) {
+            case 'contextos_build': {
+                const goal = (args as { goal: string }).goal;
+                const result = await provider.buildContext(goal);
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            case 'contextos_analyze': {
+                const query = (args as { query: string }).query;
+                const result = await provider.analyze(query);
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            case 'contextos_find': {
+                const pattern = (args as { pattern: string }).pattern;
+                const result = await provider.findFiles(pattern);
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            case 'contextos_deps': {
+                const file = (args as { file: string }).file;
+                const depth = (args as { file: string; depth?: number }).depth || 2;
+                const result = await provider.getDependencies(file, depth);
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            case 'contextos_explain': {
+                const file = (args as { file: string }).file;
+                const result = await provider.explainFile(file);
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            case 'contextos_status': {
+                const result = await provider.getStatus();
+                return {
+                    content: [{ type: 'text', text: result }],
+                };
+            }
+
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `Error: ${error instanceof Error ? error.message : String(error)}`
+            }],
+            isError: true,
+        };
+    }
+});
+
+// ═══════════════════════════════════════════════════════════
+// RESOURCES - Data that AI can read
+// ═══════════════════════════════════════════════════════════
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: RESOURCES,
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+
+    try {
+        if (uri === 'contextos://context/current') {
+            const content = await provider.getCurrentContext();
+            return {
+                contents: [{ uri, mimeType: 'text/markdown', text: content }],
+            };
+        }
+
+        if (uri === 'contextos://project/info') {
+            const content = await provider.getProjectInfo();
+            return {
+                contents: [{ uri, mimeType: 'application/json', text: content }],
+            };
+        }
+
+        if (uri === 'contextos://project/constraints') {
+            const content = await provider.getConstraints();
+            return {
+                contents: [{ uri, mimeType: 'text/markdown', text: content }],
+            };
+        }
+
+        if (uri === 'contextos://project/structure') {
+            const content = await provider.getProjectStructure();
+            return {
+                contents: [{ uri, mimeType: 'text/plain', text: content }],
+            };
+        }
+
+        throw new Error(`Unknown resource: ${uri}`);
+    } catch (error) {
+        throw new Error(`Failed to read resource: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+
+// ═══════════════════════════════════════════════════════════
+// PROMPTS - Pre-built prompt templates
+// ═══════════════════════════════════════════════════════════
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: PROMPTS,
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    switch (name) {
+        case 'code_with_context': {
+            const goal = args?.goal || 'general coding task';
+            const context = await provider.buildContext(goal);
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `# Project Context\n\n${context}\n\n# Task\n\n${goal}`,
+                        },
+                    },
+                ],
+            };
+        }
+
+        case 'review_code': {
+            const file = args?.file || '';
+            const content = await provider.getFileWithDeps(file);
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `# Code Review Request\n\nPlease review the following code and its dependencies:\n\n${content}`,
+                        },
+                    },
+                ],
+            };
+        }
+
+        case 'debug_issue': {
+            const issue = args?.issue || 'unknown issue';
+            const context = await provider.buildContext(`debug: ${issue}`);
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `# Debug Request\n\n## Issue\n${issue}\n\n## Relevant Context\n\n${context}`,
+                        },
+                    },
+                ],
+            };
+        }
+
+        default:
+            throw new Error(`Unknown prompt: ${name}`);
+    }
+});
+
+// ═══════════════════════════════════════════════════════════
+// START SERVER
+// ═══════════════════════════════════════════════════════════
+
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ContextOS MCP Server started');
+}
+
+main().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});