k0ntext 3.0.0

package/src/mcp.ts

@@ -0,0 +1,354 @@
+/**
+ * MCP Server
+ * 
+ * Model Context Protocol server for AI context.
+ * Provides tools, resources, and prompts for AI coding assistants.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { DatabaseClient } from './db/client.js';
+import { OpenRouterClient, createOpenRouterClient, hasOpenRouterKey } from './embeddings/openrouter.js';
+import { createIntelligentAnalyzer } from './analyzer/intelligent-analyzer.js';
+
+/**
+ * Server configuration
+ */
+export interface ServerConfig {
+  projectRoot: string;
+  dbPath?: string;
+  name?: string;
+  version?: string;
+}
+
+/**
+ * Tool context for handlers
+ */
+interface ToolContext {
+  db: DatabaseClient;
+  openrouter: OpenRouterClient | null;
+  projectRoot: string;
+}
+
+/**
+ * Create and start the MCP server
+ */
+export async function createServer(config: ServerConfig): Promise<McpServer> {
+  const {
+    projectRoot,
+    dbPath = '.ai-context.db',
+    name = 'k0ntext',
+    version = '1.0.0'
+  } = config;
+
+  // Initialize database
+  const db = new DatabaseClient(projectRoot, dbPath);
+
+  // Initialize OpenRouter client (optional)
+  let openrouter: OpenRouterClient | null = null;
+  if (hasOpenRouterKey()) {
+    try {
+      openrouter = createOpenRouterClient();
+    } catch (error) {
+      console.error('Warning: OpenRouter unavailable:', error);
+    }
+  }
+
+  // Create context for handlers
+  const ctx: ToolContext = { db, openrouter, projectRoot };
+
+  // Create MCP server
+  const server = new McpServer(
+    { name, version },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {}
+      }
+    }
+  );
+
+  // ==================== Register Tools ====================
+
+  // search_context - Semantic search across indexed content
+  server.registerTool(
+    'search_context',
+    {
+      description: 'Semantic search across all indexed content (workflows, agents, code, commits, docs)',
+      inputSchema: {
+        query: z.string().describe('Natural language search query'),
+        type: z.enum(['workflow', 'agent', 'command', 'code', 'commit', 'knowledge', 'config', 'doc', 'tool_config']).optional().describe('Filter by content type'),
+        limit: z.number().optional().describe('Maximum results (default: 10)')
+      }
+    },
+    async (args) => {
+      const { query, type, limit = 10 } = args as { query: string; type?: string; limit?: number };
+      
+      // Text search (semantic search requires embeddings)
+      const results = ctx.db.searchText(query, type as any);
+      
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(results.slice(0, limit), null, 2)
+        }]
+      };
+    }
+  );
+
+  // get_item - Get a specific context item
+  server.registerTool(
+    'get_item',
+    {
+      description: 'Get a specific context item by ID or path',
+      inputSchema: {
+        id: z.string().optional().describe('Context item ID'),
+        path: z.string().optional().describe('File path to look up')
+      }
+    },
+    async (args) => {
+      const { id, path: filePath } = args as { id?: string; path?: string };
+      
+      let item = null;
+      if (id) {
+        item = ctx.db.getItem(id);
+      } else if (filePath) {
+        const items = ctx.db.getAllItems().filter(i => i.filePath === filePath);
+        item = items[0] || null;
+      }
+      
+      return {
+        content: [{
+          type: 'text',
+          text: item ? JSON.stringify(item, null, 2) : 'Item not found'
+        }]
+      };
+    }
+  );
+
+  // add_knowledge - Store new knowledge
+  server.registerTool(
+    'add_knowledge',
+    {
+      description: 'Store a new insight or fact about the codebase',
+      inputSchema: {
+        name: z.string().describe('Short name for the knowledge item'),
+        content: z.string().describe('The knowledge content'),
+        relatedTo: z.array(z.string()).optional().describe('IDs of related items')
+      }
+    },
+    async (args) => {
+      const { name, content, relatedTo } = args as { name: string; content: string; relatedTo?: string[] };
+      
+      const item = ctx.db.upsertItem({
+        type: 'knowledge',
+        name,
+        content,
+        metadata: { relatedTo }
+      });
+      
+      // Add relations if specified
+      if (relatedTo) {
+        for (const targetId of relatedTo) {
+          ctx.db.addRelation({
+            sourceId: item.id,
+            targetId,
+            relationType: 'references'
+          });
+        }
+      }
+      
+      return {
+        content: [{
+          type: 'text',
+          text: `Knowledge item created: ${item.id}`
+        }]
+      };
+    }
+  );
+
+  // analyze - Run intelligent analysis
+  server.registerTool(
+    'analyze',
+    {
+      description: 'Run intelligent analysis on the codebase using OpenRouter',
+      inputSchema: {
+        type: z.enum(['full', 'docs', 'code', 'tools']).optional().describe('Analysis type')
+      }
+    },
+    async (_args) => {
+      const analyzer = createIntelligentAnalyzer(ctx.projectRoot);
+      const analysis = await analyzer.analyze();
+      
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(analysis, null, 2)
+        }]
+      };
+    }
+  );
+
+  // get_tool_configs - Get AI tool configurations
+  server.registerTool(
+    'get_tool_configs',
+    {
+      description: 'Get configurations for AI tools (Claude, Copilot, Cline, etc.)',
+      inputSchema: {
+        tool: z.enum(['claude', 'copilot', 'cline', 'antigravity', 'windsurf', 'aider', 'continue', 'cursor', 'gemini']).optional().describe('Specific tool to get configs for')
+      }
+    },
+    async (args) => {
+      const { tool } = args as { tool?: string };
+      
+      const configs = tool
+        ? ctx.db.getToolConfigs(tool as any)
+        : ctx.db.getAllToolConfigs();
+      
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(configs, null, 2)
+        }]
+      };
+    }
+  );
+
+  // query_graph - Traverse knowledge graph
+  server.registerTool(
+    'query_graph',
+    {
+      description: 'Traverse the knowledge graph from a starting point',
+      inputSchema: {
+        startId: z.string().describe('Starting context item ID'),
+        direction: z.enum(['outgoing', 'incoming', 'both']).optional().describe('Traversal direction'),
+        maxDepth: z.number().optional().describe('Maximum depth (default: 3)')
+      }
+    },
+    async (args) => {
+      const { startId, maxDepth = 3 } = args as { startId: string; maxDepth?: number };
+      
+      const results = ctx.db.traverseGraph(startId, maxDepth);
+      
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(Array.from(results.entries()), null, 2)
+        }]
+      };
+    }
+  );
+
+  // get_stats - Database statistics
+  server.registerTool(
+    'get_stats',
+    {
+      description: 'Get database and indexing statistics',
+      inputSchema: {}
+    },
+    async () => {
+      const stats = ctx.db.getStats();
+      
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(stats, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ==================== Register Prompts ====================
+
+  // context-engineer prompt
+  server.registerPrompt(
+    'context-engineer',
+    {
+      description: 'Initialize and configure the AI context system',
+      argsSchema: {
+        projectType: z.string().optional().describe('Type of project')
+      }
+    },
+    () => {
+      return {
+        messages: [{
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `You are a Context Engineer specializing in setting up AI context systems.
+
+Your goal is to analyze the current codebase and set up optimal AI context configuration.
+
+Available tools:
+- search_context: Search indexed content
+- get_item: Get specific items
+- add_knowledge: Store new insights
+- analyze: Run intelligent analysis
+- get_tool_configs: View AI tool configurations
+- get_stats: View database statistics
+
+Start by running 'analyze' to understand the codebase, then use 'add_knowledge' to capture important insights.`
+          }
+        }]
+      };
+    }
+  );
+
+  // core-architect prompt
+  server.registerPrompt(
+    'core-architect',
+    {
+      description: 'Design system architecture',
+      argsSchema: {
+        focus: z.string().optional().describe('Area to focus on')
+      }
+    },
+    (args) => {
+      const { focus } = args as { focus?: string };
+      return {
+        messages: [{
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `You are a Core Architect designing system architecture.
+${focus ? `Focus area: ${focus}` : ''}
+
+Use the context tools to understand the existing architecture and propose improvements.`
+          }
+        }]
+      };
+    }
+  );
+
+  return server;
+}
+
+/**
+ * Start the server with stdio transport
+ */
+export async function startServer(config: ServerConfig): Promise<void> {
+  const server = await createServer(config);
+  const transport = new StdioServerTransport();
+  
+  await server.connect(transport);
+  
+  console.error(`K0NTEXT MCP Server started`);
+  console.error(`Project root: ${config.projectRoot}`);
+  console.error(`Database: ${config.dbPath || '.ai-context.db'}`);
+}
+
+/**
+ * Main entry point
+ */
+export async function main(): Promise<void> {
+  const projectRoot = process.env.K0NTEXT_PROJECT_ROOT || process.cwd();
+  const dbPath = process.env.K0NTEXT_DB_PATH;
+
+  await startServer({
+    projectRoot,
+    dbPath
+  });
+}

package/templates/AI_CONTEXT.md.template

@@ -0,0 +1,245 @@
+# AI_CONTEXT.md - {{PROJECT_NAME}}
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+---
+
+## Project Identity
+
+**Platform:** {{PROJECT_DESCRIPTION}}
+**Domain:** {{PRODUCTION_URL}}
+**Tech Stack:** {{TECH_STACK}}
+**Status:** {{PROJECT_STATUS}}
+
+**Quick Reference:**
+- **API:** {{API_URL}}
+- **Repo:** {{REPO_URL}}
+- **Deploy:** {{DEPLOYMENT_PLATFORM}}
+
+---
+
+## Essential Commands
+
+### Development
+```bash
+{{INSTALL_COMMAND}}
+{{DEV_START_COMMAND}}
+```
+
+### Testing
+```bash
+{{TEST_COMMAND}}                    # All tests
+{{TEST_E2E_COMMAND}}               # E2E only
+{{TEST_COVERAGE_COMMAND}}          # With coverage
+```
+
+### Database
+```bash
+{{MIGRATION_CREATE_COMMAND}}
+{{MIGRATION_RUN_COMMAND}}
+```
+
+### Deployment
+```bash
+{{DEPLOY_COMMAND}}
+```
+
+---
+
+## Navigation Rules
+
+### High-Level Task (Refactoring a Flow)
+**Example:** "{{EXAMPLE_REFACTOR_TASK}}"
+
+**Chain:**
+1. Start: [.k0ntext/indexes/workflows/CATEGORY_INDEX.md](./.k0ntext/indexes/workflows/CATEGORY_INDEX.md)
+2. Find: Relevant category
+3. Load: Domain index
+4. Detail: Workflow file
+5. Code: [.k0ntext/indexes/code/DOMAIN_LAYER_INDEX.md](./.k0ntext/indexes/code/DOMAIN_LAYER_INDEX.md)
+6. Implement: Use appropriate specialized agent
+
+**Context Budget:** ~40k tokens (20% of 200k window)
+
+---
+
+### Low-Level Task (Fix Hardcoded Value)
+**Example:** "{{EXAMPLE_LOWLEVEL_TASK}}"
+
+**Chain:**
+1. Start: Search Patterns section below
+2. Pattern: Use grep/find
+3. Verify: [.k0ntext/indexes/code/REVERSE_INDEXES.md](./.k0ntext/indexes/code/REVERSE_INDEXES.md)
+4. Fix: Direct file edits
+5. Validate: Run tests
+
+**Context Budget:** ~15k tokens (7.5% of 200k window)
+
+---
+
+### Feature Task (Add New Feature)
+**Example:** "{{EXAMPLE_FEATURE_TASK}}"
+
+**Chain:**
+1. Start: [.k0ntext/indexes/routing/CATEGORY_INDEX.md](./.k0ntext/indexes/routing/CATEGORY_INDEX.md)
+2. Route: [.k0ntext/indexes/routing/HIGH_LEVEL_ROUTER.md](./.k0ntext/indexes/routing/HIGH_LEVEL_ROUTER.md)
+3. Research: /rpi-research
+4. Plan: /rpi-plan
+5. Implement: /rpi-implement
+
+**Context Budget:** ~50k tokens (25% of 200k window)
+
+---
+
+## Search Patterns
+
+### Finding Configuration Values
+
+**Environment variables:**
+```bash
+{{CONFIG_SEARCH_PATTERN}}
+```
+
+**Hardcoded URLs/domains:**
+```bash
+{{URL_SEARCH_PATTERN}}
+```
+
+---
+
+### Finding Business Logic
+
+**Core Files:**
+{{CORE_FILES_LIST}}
+
+---
+
+### Finding Database Schema
+
+**Models:** {{MODELS_PATH}}
+**Migrations:** {{MIGRATIONS_PATH}}
+
+---
+
+### Finding External Integrations
+
+{{EXTERNAL_INTEGRATIONS_LIST}}
+
+---
+
+## System Architecture Mini-Map
+
+{{ARCHITECTURE_DIAGRAM}}
+
+---
+
+## Index Directory
+
+**3-Level Chain:** AI_CONTEXT.md → Category (5) → Domain (15) → Detail (53)
+
+**Level 1 - Categories:** [.k0ntext/indexes/*/CATEGORY_INDEX.md](./.k0ntext/indexes/)
+- Workflows, Code, Search, Agents, Routing
+
+**Level 2 - Domains:** [.k0ntext/indexes/workflows/*.md](./.k0ntext/indexes/workflows/)
+- {{WORKFLOW_DOMAINS_COUNT}} workflow domains, {{CODE_DOMAINS_COUNT}} code domains
+
+**Level 3 - Details:** [.k0ntext/context/workflows/](./.k0ntext/context/workflows/), [.k0ntext/agents/](./.k0ntext/agents/), [.k0ntext/commands/](./.k0ntext/commands/)
+- {{WORKFLOWS_COUNT}} workflows, {{AGENTS_COUNT}} agents, {{COMMANDS_COUNT}} commands
+
+---
+
+## Critical Constants
+
+### Domain & URLs
+{{CRITICAL_URLS}}
+
+### Business Constants
+{{BUSINESS_CONSTANTS}}
+
+---
+
+## Quick Reference
+
+**Understanding:** [ARCHITECTURE_SNAPSHOT.md](./.k0ntext/context/ARCHITECTURE_SNAPSHOT.md), [workflows/CATEGORY_INDEX.md](./.k0ntext/indexes/workflows/CATEGORY_INDEX.md), [KNOWN_GOTCHAS.md](./.k0ntext/context/KNOWN_GOTCHAS.md)
+
+**Implementing:** [workflows/*.md](./.k0ntext/context/workflows/), [CODE_TO_WORKFLOW_MAP.md](./.k0ntext/context/CODE_TO_WORKFLOW_MAP.md)
+
+**Debugging:** {{DEBUGGING_QUICK_REFS}}
+
+---
+
+## Agent & Command Routing
+
+**Agents:** {{AGENT_ROUTING_TABLE}}
+**Full matrix:** [.k0ntext/indexes/agents/router.md](./.k0ntext/indexes/agents/router.md)
+
+**Commands:** /rpi-research, /rpi-plan, /rpi-implement, /verify-docs-current, /validate-all, /help, /collab, /analytics
+**All commands:** [.k0ntext/commands/](./.k0ntext/commands/)
+
+---
+
+## Gotcha Quick Reference
+
+### {{GOTCHA_CATEGORY_1}}
+{{GOTCHA_1_ITEMS}}
+
+### {{GOTCHA_CATEGORY_2}}
+{{GOTCHA_2_ITEMS}}
+
+**Full gotchas:** [.k0ntext/context/KNOWN_GOTCHAS.md](./.k0ntext/context/KNOWN_GOTCHAS.md)
+
+---
+
+## Documentation System
+
+**Navigation:** 3-level chain (AI_CONTEXT.md → Category → Domain → Detail)
+**Self-maintaining:** CODE_TO_WORKFLOW_MAP.md guides updates after code changes
+**Validation:** Run /verify-docs-current [file_path] after modifications
+**RPI Workflow:** /rpi-research → /rpi-plan → /rpi-implement
+
+**See:** [.k0ntext/RPI_WORKFLOW_PLAN.md](./.k0ntext/RPI_WORKFLOW_PLAN.md), [.k0ntext/README.md](./.k0ntext/README.md)
+
+---
+
+## Production
+
+**Platform:** {{PRODUCTION_PLATFORM}}
+**Services:** {{PRODUCTION_SERVICES}}
+**Monitoring:** {{MONITORING_COMMANDS}}
+
+---
+
+## Key Constraints
+
+**Migrations:** {{MIGRATION_CONSTRAINTS}}
+**Testing:** {{TESTING_CONSTRAINTS}}
+**Security:** {{SECURITY_CONSTRAINTS}}
+
+---
+
+## Maintenance
+
+**After changes:** Check CODE_TO_WORKFLOW_MAP.md → Update workflows → Run /verify-docs-current
+**Docs hub:** [.k0ntext/README.md](./.k0ntext/README.md)
+**RPI:** [.k0ntext/RPI_WORKFLOW_PLAN.md](./.k0ntext/RPI_WORKFLOW_PLAN.md)
+
+---
+
+## AI Tools Configuration
+
+This context is optimized for:
+- **Claude Code** - Full context reading
+- **GitHub Copilot** - See `.github/copilot-instructions.md`
+- **Cline** - See `.clinerules`
+- **Antigravity** - See `.agent/` directory
+
+---
+
+## Contact
+
+{{CONTACT_INFO}}
+
+---
+
+**Version:** 2.0 | **Last Updated:** {{DATE}} | **Context Target:** 200k
+**Architecture:** 3-Level Chain-of-Index | **Index Files:** {{INDEX_FILES_COUNT}}