agentic-knowledge-mcp 0.1.13 → 1.0.6

package/README.md

@@ -1,7 +1,6 @@
 # 🧠 Agentic Knowledge
 
-> **⚠️ WORK IN PROGRESS ⚠️**  
-> This project is under active development and not yet ready for production use. APIs may change without notice.
+A way to handle knowledge cut-off: Provide all sources you and your development team need to your agents.
 
 <div align="center">
   <h3>The End of RAG. The Dawn of Agentic Search. Maybe.</h3>
@@ -186,7 +185,7 @@ docsets:
     sources:
       - type: local_folder
         paths: ["./docs"]
-        
+
   - id: react-docs
     name: React Documentation
     description: "Official React documentation from GitHub"
@@ -217,13 +216,14 @@ docsets:
     name: My Project Docs
     sources:
       - type: local_folder
-        paths: 
-          - "./docs"           # Single directory
-          - "./guides"         # Multiple directories
-          - "./api/README.md"  # Specific files
+        paths:
+          - "./docs" # Single directory
+          - "./guides" # Multiple directories
+          - "./api/README.md" # Specific files
 ```
 
 **Benefits:**
+
 - ✅ **No file duplication** - creates symlinks to original locations
 - ✅ **Real-time updates** - changes immediately visible
 - ✅ **Relative paths** - returns clean relative paths for LLM navigation
@@ -239,11 +239,12 @@ docsets:
     sources:
       - type: git_repo
         url: "https://github.com/owner/repo.git"
-        branch: "main"              # Optional, defaults to main
+        branch: "main" # Optional, defaults to main
         paths: ["docs/", "README.md"] # Optional, extracts specific paths
 ```
 
 **Benefits:**
+
 - ✅ **Automatic downloads** - fetches latest documentation
 - ✅ **Selective extraction** - only downloads specified paths
 - ✅ **Branch selection** - target specific branches or tags
@@ -260,14 +261,14 @@ docsets:
     sources:
       - type: local_folder
         paths: ["./docs/guides"]
-        
+
   - id: api-reference
     name: API Reference
     sources:
       - type: git_repo
         url: "https://github.com/company/api-docs.git"
         paths: ["reference/"]
-        
+
   - id: mixed-sources
     name: Combined Documentation
     sources:
@@ -305,6 +306,7 @@ agentic-knowledge
 ```
 
 The server will:
+
 - ✅ Create symlinks for local folders in `.knowledge/docsets/`
 - ✅ Validate your configuration
 - ✅ Start listening for MCP requests
@@ -336,11 +338,12 @@ search_docs({
 ```
 
 **Response:**
+
 ```
 # 📚 Search My Project Documentation
 
 **Primary terms:** authentication setup
-**Related terms:** login, auth, security  
+**Related terms:** login, auth, security
 **Location:** docs
 
 ## 🔍 Search Strategy
@@ -348,7 +351,7 @@ search_docs({
 1. **Start with Specific Terms**
    Use your text search tools (grep, rg, ripgrep) to search for: `authentication setup`
 
-2. **Expand to Related Terms**  
+2. **Expand to Related Terms**
    If initial search doesn't yield results, try: `login, auth, security`
 
 3. **What to Avoid**
@@ -358,8 +361,9 @@ search_docs({
 ### Step 5: Follow the Guidance
 
 Your AI assistant will use the provided search strategy to:
+
 1. 🔍 Search your documentation with the suggested terms
-2. 📂 Navigate to the right files and directories  
+2. 📂 Navigate to the right files and directories
 3. 🎯 Find exactly what you're looking for
 4. 🔗 Follow cross-references and related content
 
@@ -378,6 +382,7 @@ docsets:
 ```
 
 **Benefits:**
+
 - Changes in your docs are immediately available
 - No copying or syncing needed
 - Works with any file type
@@ -395,8 +400,8 @@ docsets:
       - type: git_repo
         url: "https://github.com/company/design-system.git"
         paths: ["docs/"]
-        
-  - id: backend-docs  
+
+  - id: backend-docs
     name: Backend Documentation
     sources:
       - type: git_repo
@@ -413,15 +418,15 @@ Use specific and generalized keywords for better results:
 search_docs({
   docset_id: "react-docs",
   keywords: "useEffect cleanup function",
-  generalized_keywords: "hooks, lifecycle, memory management"
-})
+  generalized_keywords: "hooks, lifecycle, memory management",
+});
 
 // ❌ Too vague
 search_docs({
-  docset_id: "react-docs", 
+  docset_id: "react-docs",
   keywords: "react",
-  generalized_keywords: "javascript"
-})
+  generalized_keywords: "javascript",
+});
 ```
 
 ## 📊 Performance vs RAG

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-knowledge-mcp",
-  "version": "0.1.13",
+  "version": "1.0.6",
   "description": "A Model Context Protocol server for agentic knowledge guidance with web-based documentation loading and intelligent search instructions",
   "type": "module",
   "main": "packages/cli/dist/index.js",
@@ -29,9 +29,9 @@
     "commander": "^12.0.0",
     "chalk": "^5.3.0",
     "ora": "^8.0.1",
-    "@codemcp/knowledge-core": "0.1.13",
-    "@codemcp/knowledge-mcp-server": "0.1.13",
-    "@codemcp/knowledge-content-loader": "0.1.13"
+    "@codemcp/knowledge-core": "1.0.6",
+    "@codemcp/knowledge-mcp-server": "1.0.6",
+    "@codemcp/knowledge-content-loader": "1.0.6"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "0.16.8",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-cli",
-  "version": "0.1.13",
+  "version": "1.0.6",
   "description": "Command-line interface for agentic knowledge web content management",
   "type": "module",
   "main": "dist/exports.js",
@@ -32,9 +32,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@codemcp/knowledge-core": "^0.1.13",
-    "@codemcp/knowledge-content-loader": "^0.1.13",
-    "@codemcp/knowledge-mcp-server": "^0.1.13",
+    "@codemcp/knowledge-core": "^1.0.6",
+    "@codemcp/knowledge-content-loader": "^1.0.6",
+    "@codemcp/knowledge-mcp-server": "^1.0.6",
     "commander": "^12.0.0",
     "chalk": "^5.3.0",
     "ora": "^8.0.1"

package/packages/content-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-content-loader",
-  "version": "0.1.13",
+  "version": "1.0.6",
   "description": "Web content loading and metadata management for agentic knowledge system",
   "type": "module",
   "main": "dist/index.js",

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

@@ -9,4 +9,4 @@ export { findConfigPath, findConfigPathSync } from "./config/discovery.js";
 export { loadConfig, loadConfigSync, validateConfig } from "./config/loader.js";
 export { ConfigManager } from "./config/manager.js";
 export { calculateLocalPath, calculateLocalPathWithSymlinks, formatPath, validatePath, validatePathSync, getRelativePath, ensureKnowledgeGitignore, ensureKnowledgeGitignoreSync, } from "./paths/calculator.js";
-export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, } from "./templates/processor.js";
+export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";

package/packages/core/dist/index.js

@@ -13,4 +13,4 @@ export { ConfigManager } from "./config/manager.js";
 // Export path calculation utilities
 export { calculateLocalPath, calculateLocalPathWithSymlinks, formatPath, validatePath, validatePathSync, getRelativePath, ensureKnowledgeGitignore, ensureKnowledgeGitignoreSync, } from "./paths/calculator.js";
 // Export template processing
-export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, } from "./templates/processor.js";
+export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";

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

@@ -38,3 +38,12 @@ export declare function extractVariables(template: string): string[];
  * @returns Template context object
  */
 export declare function createTemplateContext(localPath: string, keywords: string, generalizedKeywords: string, docset: DocsetConfig): TemplateContext;
+/**
+ * Create structured search response
+ * @param instructions - Processed instruction text
+ * @param keywords - Search keywords
+ * @param generalizedKeywords - Generalized keywords
+ * @param localPath - Calculated local path
+ * @returns Structured response object
+ */
+export declare function createStructuredResponse(instructions: string, keywords: string, generalizedKeywords: string, localPath: string): import("../types.js").SearchDocsResponse;

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

@@ -109,3 +109,19 @@ export function createTemplateContext(localPath, keywords, generalizedKeywords,
         docset,
     };
 }
+/**
+ * Create structured search response
+ * @param instructions - Processed instruction text
+ * @param keywords - Search keywords
+ * @param generalizedKeywords - Generalized keywords
+ * @param localPath - Calculated local path
+ * @returns Structured response object
+ */
+export function createStructuredResponse(instructions, keywords, generalizedKeywords, localPath) {
+    return {
+        instructions,
+        search_terms: keywords,
+        generalized_search_terms: generalizedKeywords,
+        path: localPath,
+    };
+}

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

@@ -77,14 +77,12 @@ export interface SearchDocsParams {
 export interface SearchDocsResponse {
     /** Instructions for the agent on how to search */
     instructions: string;
-    /** The docset that was searched */
-    docset: string;
+    /** The processed keywords for searching */
+    search_terms: string;
+    /** The processed generalized keywords for broader context */
+    generalized_search_terms: string;
     /** The calculated local path for searching */
-    local_path: string;
-    /** Keywords that were processed */
-    keywords: string;
-    /** Generalized keywords that were processed */
-    generalized_keywords: string;
+    path: string;
 }
 /**
  * Response from the list_docsets tool
@@ -130,7 +128,7 @@ export declare class KnowledgeError extends Error {
 /**
  * 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";
+export declare const DEFAULT_TEMPLATE = "Use text search tools (grep, rg, ripgrep) to search for {{keywords}} in {{local_path}}. Try broader terms if needed. Skip: node_modules/, .git/, build/, dist/.";
 /**
  * Allowed template variables that can be used in instruction templates
  */

package/packages/core/dist/types.js

@@ -29,31 +29,7 @@ export class KnowledgeError extends Error {
 /**
  * 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
-`;
+export const DEFAULT_TEMPLATE = `Use text search tools (grep, rg, ripgrep) to search for {{keywords}} in {{local_path}}. Try broader terms if needed. Skip: node_modules/, .git/, build/, dist/.`;
 /**
  * Allowed template variables that can be used in instruction templates
  */

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-core",
-  "version": "0.1.13",
+  "version": "1.0.6",
   "description": "Core functionality for agentic knowledge guidance system",
   "type": "module",
   "main": "dist/index.js",

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

@@ -4,7 +4,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { loadConfig, findConfigPath, calculateLocalPath, processTemplate, createTemplateContext, getEffectiveTemplate, } from "@codemcp/knowledge-core";
+import { loadConfig, findConfigPath, calculateLocalPath, processTemplate, createTemplateContext, getEffectiveTemplate, createStructuredResponse, } from "@codemcp/knowledge-core";
 /**
  * Create an agentic knowledge MCP server
  * @returns MCP server instance
@@ -64,14 +64,19 @@ export function createAgenticKnowledgeServer() {
                 return `• **${docset.id}** (${docset.name})${description}`;
             })
                 .join("\n");
-            const searchDocsDescription = `Search for documentation in available docsets. Returns structured search strategy.
+            const searchDocsDescription = `Search for documentation in available docsets. Returns structured response with search instructions and parameters.
 
 📚 **AVAILABLE DOCSETS:**
 ${docsetInfo}
 
-🔍 **SEARCH STRATEGY:**
-- Use the tools you have to search in text files (grep, rg, ripgrep, find)
-- Start with specific terms, expand to generalized terms`;
+🔍 **STRUCTURED RESPONSE:**
+Returns JSON object with:
+- instructions: Search guidance text
+- search_terms: Primary keywords to search for
+- generalized_search_terms: Broader terms for context
+- path: Local directory path to search in
+
+Use the path and search terms with your text search tools (grep, rg, ripgrep, find).`;
             return {
                 tools: [
                     {
@@ -178,13 +183,10 @@ ${docsetInfo}
                     // Get effective template and process it
                     const effectiveTemplate = getEffectiveTemplate(docset, config.template);
                     const instructions = processTemplate(effectiveTemplate, templateContext);
+                    // Create structured response
+                    const structuredResponse = createStructuredResponse(instructions, keywords.trim(), (generalized_keywords || "").trim(), localPath);
                     return {
-                        content: [
-                            {
-                                type: "text",
-                                text: instructions,
-                            },
-                        ],
+                        structuredContent: structuredResponse,
                     };
                 }
                 case "list_docsets": {

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-mcp-server",
-  "version": "0.1.13",
+  "version": "1.0.6",
   "description": "MCP server implementation for agentic knowledge guidance system",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@codemcp/knowledge-core": "^0.1.13",
+    "@codemcp/knowledge-core": "^1.0.6",
     "@modelcontextprotocol/sdk": "^1.19.1"
   },
   "devDependencies": {