agentic-knowledge-mcp 0.0.1

package/packages/core/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * @codemcp/knowledge-core
+ *
+ * Core functionality for the agentic knowledge guidance system.
+ * Provides configuration discovery, path calculation, and template processing.
+ */
+// Export all types and interfaces
+export * from "./types.js";
+// Export configuration functionality
+export { findConfigPath, findConfigPathSync } from "./config/discovery.js";
+export { loadConfig, loadConfigSync, validateConfig } from "./config/loader.js";
+export { ConfigManager } from "./config/manager.js";
+// Export path calculation utilities
+export {
+  calculateLocalPath,
+  formatPath,
+  validatePath,
+  validatePathSync,
+  getRelativePath,
+  ensureKnowledgeGitignore,
+  ensureKnowledgeGitignoreSync,
+} from "./paths/calculator.js";
+// Export template processing
+export {
+  processTemplate,
+  getEffectiveTemplate,
+  validateTemplate,
+  extractVariables,
+  createTemplateContext,
+} from "./templates/processor.js";

package/packages/core/dist/paths/calculator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Path calculation utilities
+ */
+import type { DocsetConfig } from "../types.js";
+/**
+ * Calculate the local path for a docset
+ * @param docset - Docset configuration
+ * @param configPath - Path to the configuration file
+ * @returns Calculated local path
+ */
+export declare function calculateLocalPath(docset: DocsetConfig, configPath: string): string;
+/**
+ * Ensure .knowledge/.gitignore exists with docsets/ ignored
+ * @param configPath - Path to the configuration file
+ */
+export declare function ensureKnowledgeGitignore(configPath: string): Promise<void>;
+/**
+ * Synchronous version of ensureKnowledgeGitignore
+ * @param configPath - Path to the configuration file
+ */
+export declare function ensureKnowledgeGitignoreSync(configPath: string): void;
+/**
+ * Format a path for use in instructions (normalize separators, etc.)
+ * @param path - Path to format
+ * @returns Formatted path
+ */
+export declare function formatPath(path: string): string;
+/**
+ * Validate that a path is accessible and exists
+ * @param path - Path to validate
+ * @returns True if path exists and is accessible
+ */
+export declare function validatePath(path: string): Promise<boolean>;
+/**
+ * Synchronous version of validatePath
+ * @param path - Path to validate
+ * @returns True if path exists and is accessible
+ */
+export declare function validatePathSync(path: string): boolean;
+/**
+ * Get relative path from one location to another (useful for instructions)
+ * @param from - Starting path
+ * @param to - Target path
+ * @returns Relative path from 'from' to 'to'
+ */
+export declare function getRelativePath(from: string, to: string): string;

package/packages/core/dist/paths/calculator.js

@@ -0,0 +1,166 @@
+/**
+ * Path calculation utilities
+ */
+import { resolve, dirname, isAbsolute, join, normalize } from "node:path";
+import { promises as fs } from "node:fs";
+import * as fsSync from "node:fs";
+import * as pathModule from "node:path";
+import { KnowledgeError, ErrorType } from "../types.js";
+/**
+ * Calculate the local path for a docset
+ * @param docset - Docset configuration
+ * @param configPath - Path to the configuration file
+ * @returns Calculated local path
+ */
+export function calculateLocalPath(docset, configPath) {
+  try {
+    const configDir = dirname(configPath); // This is the .knowledge directory
+    // For docsets with web sources, use standardized path: .knowledge/docsets/{id}
+    if (docset.web_sources && docset.web_sources.length > 0) {
+      return join(configDir, "docsets", docset.id);
+    }
+    // For traditional local docsets, use the configured local_path
+    if (!docset.local_path) {
+      throw new Error(
+        "Docset must have either web_sources or local_path configured",
+      );
+    }
+    const projectRoot = dirname(configDir); // This is the project root
+    // If the path is absolute, use it as-is
+    if (isAbsolute(docset.local_path)) {
+      return normalize(docset.local_path);
+    }
+    // If relative, resolve relative to project root directory
+    const resolvedPath = resolve(projectRoot, docset.local_path);
+    return normalize(resolvedPath);
+  } catch (error) {
+    throw new KnowledgeError(
+      ErrorType.PATH_INVALID,
+      `Failed to calculate local path for docset '${docset.id}': ${error.message}`,
+      { docset, configPath, error },
+    );
+  }
+}
+/**
+ * Ensure .knowledge/.gitignore exists with docsets/ ignored
+ * @param configPath - Path to the configuration file
+ */
+export async function ensureKnowledgeGitignore(configPath) {
+  try {
+    const configDir = dirname(configPath);
+    const gitignorePath = join(configDir, ".gitignore");
+    // Check if .gitignore already exists
+    try {
+      const content = await fs.readFile(gitignorePath, "utf-8");
+      // Check if it already contains docsets/ ignore rule
+      if (content.includes("docsets/")) {
+        return; // Already configured
+      }
+      // Append to existing file
+      await fs.appendFile(
+        gitignorePath,
+        "\n# Agentic Knowledge - Downloaded docsets\ndocsets/\n",
+      );
+    } catch (error) {
+      // File doesn't exist, create it
+      if (error.code === "ENOENT") {
+        await fs.writeFile(
+          gitignorePath,
+          "# Agentic Knowledge - Downloaded docsets\ndocsets/\n",
+        );
+      } else {
+        throw error;
+      }
+    }
+  } catch (error) {
+    // Don't fail the entire operation if gitignore creation fails
+    console.warn(
+      `Warning: Could not create .knowledge/.gitignore: ${error.message}`,
+    );
+  }
+}
+/**
+ * Synchronous version of ensureKnowledgeGitignore
+ * @param configPath - Path to the configuration file
+ */
+export function ensureKnowledgeGitignoreSync(configPath) {
+  try {
+    const configDir = dirname(configPath);
+    const gitignorePath = join(configDir, ".gitignore");
+    // Check if .gitignore already exists
+    try {
+      const content = fsSync.readFileSync(gitignorePath, "utf-8");
+      // Check if it already contains docsets/ ignore rule
+      if (content.includes("docsets/")) {
+        return; // Already configured
+      }
+      // Append to existing file
+      fsSync.appendFileSync(
+        gitignorePath,
+        "\n# Agentic Knowledge - Downloaded docsets\ndocsets/\n",
+      );
+    } catch (error) {
+      // File doesn't exist, create it
+      if (error.code === "ENOENT") {
+        fsSync.writeFileSync(
+          gitignorePath,
+          "# Agentic Knowledge - Downloaded docsets\ndocsets/\n",
+        );
+      } else {
+        throw error;
+      }
+    }
+  } catch (error) {
+    // Don't fail the entire operation if gitignore creation fails
+    console.warn(
+      `Warning: Could not create .knowledge/.gitignore: ${error.message}`,
+    );
+  }
+}
+/**
+ * Format a path for use in instructions (normalize separators, etc.)
+ * @param path - Path to format
+ * @returns Formatted path
+ */
+export function formatPath(path) {
+  // Normalize path separators and remove redundant separators
+  const normalized = normalize(path);
+  // Ensure path ends with separator for directory paths (if it looks like a directory)
+  // This helps with search instructions that need to specify directories
+  return normalized;
+}
+/**
+ * Validate that a path is accessible and exists
+ * @param path - Path to validate
+ * @returns True if path exists and is accessible
+ */
+export async function validatePath(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Synchronous version of validatePath
+ * @param path - Path to validate
+ * @returns True if path exists and is accessible
+ */
+export function validatePathSync(path) {
+  try {
+    fsSync.accessSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Get relative path from one location to another (useful for instructions)
+ * @param from - Starting path
+ * @param to - Target path
+ * @returns Relative path from 'from' to 'to'
+ */
+export function getRelativePath(from, to) {
+  return pathModule.relative(from, to);
+}

package/packages/core/dist/templates/processor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Template processing functionality
+ */
+import type { TemplateContext, DocsetConfig } from "../types.js";
+/**
+ * Process a template with variable substitution
+ * @param template - Template string with variables
+ * @param context - Context data for substitution
+ * @returns Processed template string
+ */
+export declare function processTemplate(template: string, context: TemplateContext): string;
+/**
+ * Get the effective template for a docset (docset template or global template or default)
+ * @param docset - Docset configuration
+ * @param globalTemplate - Global template from config (optional)
+ * @returns Template string to use
+ */
+export declare function getEffectiveTemplate(docset: DocsetConfig, globalTemplate?: string): string;
+/**
+ * Validate that a template contains only allowed variables and has required variables
+ * This is called during configuration loading to fail fast on invalid templates
+ * @param template - Template string to validate
+ * @returns True if template is valid, throws KnowledgeError if invalid
+ */
+export declare function validateTemplate(template: string): boolean;
+/**
+ * Extract variable names from a template
+ * @param template - Template string
+ * @returns Array of variable names found in the template
+ */
+export declare function extractVariables(template: string): string[];
+/**
+ * Create template context from search parameters
+ * @param localPath - Calculated local path
+ * @param keywords - Search keywords
+ * @param generalizedKeywords - Generalized keywords
+ * @param docset - Docset configuration
+ * @returns Template context object
+ */
+export declare function createTemplateContext(localPath: string, keywords: string, generalizedKeywords: string, docset: DocsetConfig): TemplateContext;

package/packages/core/dist/templates/processor.js

@@ -0,0 +1,111 @@
+/**
+ * Template processing functionality
+ */
+import { KnowledgeError, ErrorType, DEFAULT_TEMPLATE, ALLOWED_TEMPLATE_VARIABLES, REQUIRED_TEMPLATE_VARIABLES, } from "../types.js";
+/**
+ * Process a template with variable substitution
+ * @param template - Template string with variables
+ * @param context - Context data for substitution
+ * @returns Processed template string
+ */
+export function processTemplate(template, context) {
+    try {
+        let processed = template;
+        // Replace template variables using double curly brace syntax
+        const variables = {
+            local_path: context.local_path,
+            keywords: context.keywords,
+            generalized_keywords: context.generalized_keywords,
+            docset_id: context.docset.id,
+            docset_name: context.docset.name,
+            docset_description: context.docset.description || "",
+        };
+        // Replace each variable
+        for (const [key, value] of Object.entries(variables)) {
+            const regex = new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, "g");
+            processed = processed.replace(regex, value);
+        }
+        // Check for unreplaced variables - this should never happen in production
+        // because templates are validated at startup
+        const unreplacedMatches = processed.match(/\{\{[^}]+\}\}/g);
+        if (unreplacedMatches) {
+            throw new KnowledgeError(ErrorType.TEMPLATE_ERROR, `Template contains invalid variables: ${unreplacedMatches.join(", ")}`, { template, unreplacedMatches });
+        }
+        return processed.trim();
+    }
+    catch (error) {
+        if (error instanceof KnowledgeError) {
+            throw error;
+        }
+        throw new KnowledgeError(ErrorType.TEMPLATE_ERROR, `Failed to process template: ${error.message}`, { template, context, error });
+    }
+}
+/**
+ * Get the effective template for a docset (docset template or global template or default)
+ * @param docset - Docset configuration
+ * @param globalTemplate - Global template from config (optional)
+ * @returns Template string to use
+ */
+export function getEffectiveTemplate(docset, globalTemplate) {
+    // Priority: docset template > global template > default template
+    return docset.template || globalTemplate || DEFAULT_TEMPLATE;
+}
+/**
+ * Validate that a template contains only allowed variables and has required variables
+ * This is called during configuration loading to fail fast on invalid templates
+ * @param template - Template string to validate
+ * @returns True if template is valid, throws KnowledgeError if invalid
+ */
+export function validateTemplate(template) {
+    // Extract all variables from template
+    const variables = extractVariables(template);
+    // Check for invalid variables
+    const invalidVariables = variables.filter((variable) => !ALLOWED_TEMPLATE_VARIABLES.includes(variable));
+    if (invalidVariables.length > 0) {
+        throw new KnowledgeError(ErrorType.TEMPLATE_ERROR, `Template contains invalid variables: ${invalidVariables.join(", ")}. Allowed variables: ${ALLOWED_TEMPLATE_VARIABLES.join(", ")}`, {
+            template,
+            invalidVariables,
+            allowedVariables: ALLOWED_TEMPLATE_VARIABLES,
+        });
+    }
+    // Check for required variables
+    const missingRequired = REQUIRED_TEMPLATE_VARIABLES.filter((required) => !variables.includes(required));
+    if (missingRequired.length > 0) {
+        throw new KnowledgeError(ErrorType.TEMPLATE_ERROR, `Template missing required variables: ${missingRequired.join(", ")}. Required variables: ${REQUIRED_TEMPLATE_VARIABLES.join(", ")}`, {
+            template,
+            missingRequired,
+            requiredVariables: REQUIRED_TEMPLATE_VARIABLES,
+        });
+    }
+    return true;
+}
+/**
+ * Extract variable names from a template
+ * @param template - Template string
+ * @returns Array of variable names found in the template
+ */
+export function extractVariables(template) {
+    const matches = template.match(/\{\{\s*([^}]+)\s*\}\}/g);
+    if (!matches)
+        return [];
+    return matches.map((match) => {
+        const varName = match.replace(/\{\{\s*/, "").replace(/\s*\}\}/, "");
+        return varName.trim();
+    });
+}
+/**
+ * Create template context from search parameters
+ * @param localPath - Calculated local path
+ * @param keywords - Search keywords
+ * @param generalizedKeywords - Generalized keywords
+ * @param docset - Docset configuration
+ * @returns Template context object
+ */
+export function createTemplateContext(localPath, keywords, generalizedKeywords, docset) {
+    return {
+        local_path: localPath,
+        keywords,
+        generalized_keywords: generalizedKeywords,
+        docset,
+    };
+}

package/packages/core/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Core types and interfaces for the agentic knowledge guidance system
+ */
+/**
+ * Configuration for a single docset
+ */
+export interface DocsetConfig {
+    /** Unique identifier for the docset */
+    id: string;
+    /** Human-readable name of the docset */
+    name: string;
+    /** Description of what this docset contains */
+    description?: string;
+    /** Path to the documentation (relative to .knowledge folder or absolute) - optional for web sources */
+    local_path?: string;
+    /** Optional custom instruction template for this docset */
+    template?: string;
+    /** Optional web sources to load content from */
+    web_sources?: WebSourceConfig[];
+}
+/**
+ * Basic web source configuration (for core package validation)
+ */
+export interface WebSourceConfig {
+    /** URL of the web source */
+    url: string;
+    /** Type of web source */
+    type: string;
+    /** Type-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Main configuration structure for the knowledge system
+ */
+export interface KnowledgeConfig {
+    /** Version of the configuration format */
+    version: string;
+    /** List of docsets available for search */
+    docsets: DocsetConfig[];
+    /** Global instruction template (optional) */
+    template?: string;
+}
+/**
+ * Parameters for the search_docs tool
+ */
+export interface SearchDocsParams {
+    /** ID of the docset to search */
+    docset: string;
+    /** Specific keywords to search for */
+    keywords: string;
+    /** Generalized keywords for broader search context */
+    generalized_keywords: string;
+}
+/**
+ * Response from the search_docs tool
+ */
+export interface SearchDocsResponse {
+    /** Instructions for the agent on how to search */
+    instructions: string;
+    /** The docset that was searched */
+    docset: string;
+    /** The calculated local path for searching */
+    local_path: string;
+    /** Keywords that were processed */
+    keywords: string;
+    /** Generalized keywords that were processed */
+    generalized_keywords: string;
+}
+/**
+ * Response from the list_docsets tool
+ */
+export interface ListDocsetsResponse {
+    /** List of available docsets */
+    docsets: DocsetConfig[];
+    /** Total number of docsets */
+    count: number;
+}
+/**
+ * Template context for instruction generation
+ */
+export interface TemplateContext {
+    /** Path to search in */
+    local_path: string;
+    /** Keywords to search for */
+    keywords: string;
+    /** Generalized keywords */
+    generalized_keywords: string;
+    /** Docset information */
+    docset: DocsetConfig;
+}
+/**
+ * Error types that can occur in the core system
+ */
+export declare enum ErrorType {
+    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
+    CONFIG_INVALID = "CONFIG_INVALID",
+    DOCSET_NOT_FOUND = "DOCSET_NOT_FOUND",
+    PATH_INVALID = "PATH_INVALID",
+    TEMPLATE_ERROR = "TEMPLATE_ERROR",
+    YAML_PARSE_ERROR = "YAML_PARSE_ERROR"
+}
+/**
+ * Custom error class for knowledge system errors
+ */
+export declare class KnowledgeError extends Error {
+    type: ErrorType;
+    context?: Record<string, unknown> | undefined;
+    constructor(type: ErrorType, message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Default instruction template
+ */
+export declare const DEFAULT_TEMPLATE = "# \uD83D\uDCDA Search {{docset_name}} Documentation\n\n**Primary terms:** {{keywords}}  \n**Related terms:** {{generalized_keywords}}  \n**Location:** {{local_path}}\n\n## \uD83D\uDD0D Search Strategy\n\n### 1. **Start with Specific Terms**\nUse your text search tools (grep, rg, ripgrep) to search for: `{{keywords}}`\n\n### 2. **Expand to Related Terms**\nIf initial search doesn't yield results, try: `{{generalized_keywords}}`\n\n### 3. **What to Avoid**\nSkip these directories to save time:\n- `node_modules/`, `.git/`, `.knowledge/`\n- `build/`, `dist/`, `target/`, `vendor/`\n\n## \uD83D\uDCA1 Search Tips\n- Use **case-insensitive** search when possible\n- Look for **exact matches first**, then partial matches\n- Check **cross-references** and `See also` sections\n- If stuck, try **broader terms** or ask the user to clarify\n";
+/**
+ * Allowed template variables that can be used in instruction templates
+ */
+export declare const ALLOWED_TEMPLATE_VARIABLES: readonly ["local_path", "keywords", "generalized_keywords", "docset_id", "docset_name", "docset_description"];
+/**
+ * Required template variables that must be present in every template
+ */
+export declare const REQUIRED_TEMPLATE_VARIABLES: readonly ["local_path", "keywords"];
+/**
+ * Configuration file name pattern
+ */
+export declare const CONFIG_FILENAME = "config.yaml";
+/**
+ * Configuration directory name
+ */
+export declare const CONFIG_DIR = ".knowledge";

package/packages/core/dist/types.js

@@ -0,0 +1,79 @@
+/**
+ * Core types and interfaces for the agentic knowledge guidance system
+ */
+/**
+ * Error types that can occur in the core system
+ */
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["CONFIG_NOT_FOUND"] = "CONFIG_NOT_FOUND";
+    ErrorType["CONFIG_INVALID"] = "CONFIG_INVALID";
+    ErrorType["DOCSET_NOT_FOUND"] = "DOCSET_NOT_FOUND";
+    ErrorType["PATH_INVALID"] = "PATH_INVALID";
+    ErrorType["TEMPLATE_ERROR"] = "TEMPLATE_ERROR";
+    ErrorType["YAML_PARSE_ERROR"] = "YAML_PARSE_ERROR";
+})(ErrorType || (ErrorType = {}));
+/**
+ * Custom error class for knowledge system errors
+ */
+export class KnowledgeError extends Error {
+    type;
+    context;
+    constructor(type, message, context) {
+        super(message);
+        this.type = type;
+        this.context = context;
+        this.name = "KnowledgeError";
+    }
+}
+/**
+ * Default instruction template
+ */
+export const DEFAULT_TEMPLATE = `# 📚 Search {{docset_name}} Documentation
+
+**Primary terms:** {{keywords}}  
+**Related terms:** {{generalized_keywords}}  
+**Location:** {{local_path}}
+
+## 🔍 Search Strategy
+
+### 1. **Start with Specific Terms**
+Use your text search tools (grep, rg, ripgrep) to search for: \`{{keywords}}\`
+
+### 2. **Expand to Related Terms**
+If initial search doesn't yield results, try: \`{{generalized_keywords}}\`
+
+### 3. **What to Avoid**
+Skip these directories to save time:
+- \`node_modules/\`, \`.git/\`, \`.knowledge/\`
+- \`build/\`, \`dist/\`, \`target/\`, \`vendor/\`
+
+## 💡 Search Tips
+- Use **case-insensitive** search when possible
+- Look for **exact matches first**, then partial matches
+- Check **cross-references** and \`See also\` sections
+- If stuck, try **broader terms** or ask the user to clarify
+`;
+/**
+ * Allowed template variables that can be used in instruction templates
+ */
+export const ALLOWED_TEMPLATE_VARIABLES = [
+    "local_path",
+    "keywords",
+    "generalized_keywords",
+    "docset_id",
+    "docset_name",
+    "docset_description",
+];
+/**
+ * Required template variables that must be present in every template
+ */
+export const REQUIRED_TEMPLATE_VARIABLES = ["local_path", "keywords"];
+/**
+ * Configuration file name pattern
+ */
+export const CONFIG_FILENAME = "config.yaml";
+/**
+ * Configuration directory name
+ */
+export const CONFIG_DIR = ".knowledge";

package/packages/core/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@codemcp/knowledge-core",
+  "version": "0.0.1",
+  "description": "Core functionality for agentic knowledge guidance system",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rimraf dist",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "lint": "oxlint && eslint .",
+    "lint:fix": "oxlint --fix && eslint . --fix",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.3.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "agentic",
+    "knowledge",
+    "configuration",
+    "path-calculation",
+    "templates"
+  ],
+  "author": "Oliver Jägle <github@beimir.net>",
+  "license": "MIT"
+}

package/packages/mcp-server/dist/bin.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Binary entry point for the agentic-knowledge MCP server
+ */
+export {};

package/packages/mcp-server/dist/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Binary entry point for the agentic-knowledge MCP server
+ */
+import { startServer } from "./cli.js";
+// Start the server
+startServer().catch((error) => {
+    console.error("Failed to start agentic-knowledge server:", error);
+    process.exit(1);
+});

package/packages/mcp-server/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI functionality for the MCP server
+ */
+/**
+ * Start the agentic knowledge MCP server from CLI
+ */
+export declare function startServer(): Promise<void>;