agentic-knowledge-mcp 0.1.13 → 1.0.9

package/README.md

@@ -1,484 +1,134 @@
 # 🧠 Agentic Knowledge
 
-> **⚠️ WORK IN PROGRESS ⚠️**  
-> This project is under active development and not yet ready for production use. APIs may change without notice.
+**Search any documentation as if you had written it yourself**
 
-<div align="center">
-  <h3>The End of RAG. The Dawn of Agentic Search. Maybe.</h3>
-  <p><em>Intelligent navigation instructions that guide AI assistants through documentation using filesystem-like exploration instead of traditional retrieval</em></p>
-
-  <a href="https://github.com/yourusername/agentic-knowledge/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/yourusername/agentic-knowledge.svg?style=for-the-badge" alt="License" />
-  </a>
-  <a href="https://linkedin.com/in/yourusername">
-    <img src="https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555" alt="LinkedIn" />
-  </a>
-</div>
+An MCP server that guides AI assistants to navigate documentation using their built-in tools (grep, file reading) instead of traditional RAG. Leverages ever growing capabilities of large language models, better tool-calling and interpretation and agentic search patterns for precise, intelligent documentation discovery.
 
 ---
 
-## 🎯 What Is This?
-
-**Agentic Knowledge** represents a fundamental paradigm shift away from traditional Retrieval-Augmented Generation (RAG) toward **agentic search patterns**. Instead of chunking documents, computing embeddings, and retrieving fragments, this system provides **intelligent navigation instructions** that leverage the AI agent's existing tools (grep, ripgrep, file reading) and the explosion of context windows.
-
-### The Core Insight
-
-Modern AI assistants are **context-rich** (200K+ tokens) and equipped with powerful filesystem tools. Rather than building complex search infrastructure, we can guide them to navigate documentation intelligently—just like Claude Code revolutionized code analysis by ditching RAG for direct filesystem exploration.
-
-## 🪦 Why RAG is Dead
-
-_Inspired by [The RAG Obituary](https://www.nicolasbustamante.com/p/the-rag-obituary-killed-by-agents) by Nicolas Bustamante_
-
-Traditional RAG was a brilliant workaround for the **context-poor era** (GPT-4's 8K tokens). But it came with fundamental limitations:
-
-### The RAG Problem Stack
-
-```
-❌ Chunking destroys document relationships
-❌ Embeddings fail on precise terminology
-❌ Similarity search misses exact matches
-❌ Reranking adds latency and complexity
-❌ Context fragmentation loses coherence
-❌ Infrastructure burden is massive
-```
-
-### The Agentic Solution
-
-```
-✅ Direct filesystem navigation
-✅ Intelligent reference following
-✅ Complete document context
-✅ Zero infrastructure overhead
-✅ Sub-10ms response times
-✅ Deterministic, precise results
-```
-
-## 🔄 From Retrieval to Navigation
-
-Traditional RAG says: _"Here are 50 fragments that mention your keywords"_
-
-Agentic Knowledge says: _"Search for 'useState' in `./docs/react-18.2/hooks/`. If that doesn't help, try 'state management' in `./docs/patterns/`. Follow any 'See also' references you find."_
-
-The difference? **Guidance over fragments. Investigation over retrieval.**
-
-## 🏗 How It Works
+## 🎯 What Is This For?
 
-### MCP Server Integration
-
-Implements the [Model Context Protocol](https://modelcontextprotocol.io/) with two core tools:
-
-```typescript
-// Get navigation guidance for specific queries
-search_docs({
-  docset: "react-docs",
-  keywords: ["useEffect", "cleanup"],
-  generalized_keywords: ["lifecycle", "memory"],
-});
-
-// Discover available documentation sets
-list_docsets();
-```
-
-### Configuration-Driven Intelligence
-
-Simple `.knowledge/config.yaml` pattern:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: react-docs
-    name: React Documentation
-    description: "React framework documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs/react-18.2"]
-    template: |
-      Search for '{{keywords}}' in {{local_path}}/hooks/. 
-      If not found, try '{{generalized_keywords}}' in {{local_path}}/patterns/.
-      Follow any cross-references you discover.
-```
-
-### The Navigation Response
-
-Instead of document fragments, you get **actionable instructions**:
-
-```
-Based on your React useEffect cleanup query:
-
-1. Start with `./docs/react-18.2/hooks/effect.md` - contains useEffect fundamentals
-2. Search for "cleanup function" patterns in `./docs/react-18.2/patterns/`
-3. Check `./examples/lifecycle/` for practical cleanup implementations
-4. Review `./docs/react-18.2/performance/memory.md` for memory leak prevention
-
-Focus on the cleanup function return pattern and dependency array management.
-```
+Give your AI assistant access to any documentation—yours or third-party—so it can find answers as naturally as you would. No embeddings, no vector databases, no complex infrastructure.
 
-## 🚀 Why This Matters
-
-### The Context Revolution
-
-- **2022**: GPT-4 had 8K tokens (~12 pages)
-- **2025**: Claude Sonnet has 200K tokens (~700 pages)
-- **Future**: Heading toward 2M+ tokens (~6,000 pages)
-
-### The Tool Evolution
-
-AI assistants now have sophisticated filesystem tools:
-
-- **Grep/Ripgrep**: Lightning-fast regex search through files
-- **Glob**: Direct file discovery by patterns
-- **Direct File Access**: Read complete documents in context
-- **Reference Following**: Navigate cross-references naturally
-
-### The Infrastructure Shift
-
-- **RAG**: Elasticsearch clusters, embedding models, rerankers, vector databases
-- **Agentic**: Simple YAML config, zero infrastructure, filesystem tools
-
-## 🎯 Core Principles
-
-### 1. **Guidance Over Search**
-
-Provide intelligent navigation instructions instead of search results
-
-### 2. **Context Abundance**
-
-Leverage massive context windows instead of working around limitations
-
-### 3. **Tool Evolution Compatibility**
-
-Instructions remain stable as agent capabilities evolve (grep → AST parsing → future tools)
-
-### 4. **Zero AI Dependency**
-
-Pure logic-based guidance for reliability and speed
-
-### 5. **Investigation Over Retrieval**
-
-Agents follow references and build understanding incrementally
+**Perfect for:**
+- 📚 **Project documentation** - Your team's internal docs, APIs, guides
+- 🔧 **Framework references** - React, TypeScript, MCP SDK, any library
+- 🏢 **Enterprise knowledge** - Company wikis, architecture docs, runbooks
+- 🌐 **Open source projects** - Clone any repo's docs for instant access
 
 ## 🚀 Quick Start
 
-### Installation
-
-```bash
-npm install -g agentic-knowledge
-# or
-npx agentic-knowledge
-```
-
-### Basic Setup
-
-1. **Create configuration directory**:
-
-```bash
-mkdir .knowledge
-```
-
-2. **Add configuration** (`.knowledge/config.yaml`):
-
-```yaml
-version: "1.0"
-docsets:
-  - id: my-docs
-    name: My Project Documentation
-    description: "Local project documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs"]
-        
-  - id: react-docs
-    name: React Documentation
-    description: "Official React documentation from GitHub"
-    sources:
-      - type: git_repo
-        url: "https://github.com/facebook/react.git"
-        branch: "main"
-        paths: ["docs/"]
-```
-
-3. **Start the MCP server**:
-
-```bash
-agentic-knowledge
-```
-
-4. **Connect your AI assistant** using MCP protocol
-
-## 📋 Configuration Guide
-
-### Local Folder Sources
-
-For documentation stored locally in your project:
-
-```yaml
-docsets:
-  - id: my-project
-    name: My Project Docs
-    sources:
-      - type: local_folder
-        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
-
-### Git Repository Sources
-
-For documentation from remote repositories:
-
-```yaml
-docsets:
-  - id: external-docs
-    name: External Documentation
-    sources:
-      - type: git_repo
-        url: "https://github.com/owner/repo.git"
-        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
-
-### Mixed Configuration
-
-Combine local and remote sources in one configuration:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: local-guides
-    name: Local User Guides
-    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:
-      - type: local_folder
-        paths: ["./internal-docs"]
-      - type: git_repo
-        url: "https://github.com/external/docs.git"
-```
-
-## 🎯 How to Use
-
-### Step 1: Set Up Your Documentation
-
-Create a `.knowledge/config.yaml` file in your project root:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: my-project
-    name: My Project Documentation
-    description: "Main project documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs", "./README.md"]
-```
-
-### Step 2: Start the MCP Server
-
-```bash
-# Install globally
-npm install -g agentic-knowledge
-
-# Start the server
-agentic-knowledge
-```
-
-The server will:
-- ✅ Create symlinks for local folders in `.knowledge/docsets/`
-- ✅ Validate your configuration
-- ✅ Start listening for MCP requests
-
-### Step 3: Connect Your AI Assistant
-
-Configure your AI assistant (Claude Desktop, etc.) to use the MCP server:
+### 1. Configure an MCP Client
 
+Add to your coding agent config something along the lines of 
 ```json
 {
   "mcpServers": {
     "agentic-knowledge": {
-      "command": "agentic-knowledge"
+      "command": "npx",
+      "args": ["-y", "agentic-knowledge-mcp"]
     }
   }
 }
 ```
 
-### Step 4: Search Your Documentation
-
-Use the `search_docs` tool in your AI assistant:
-
-```
-search_docs({
-  docset_id: "my-project",
-  keywords: "authentication setup",
-  generalized_keywords: "login, auth, security"
-})
-```
-
-**Response:**
-```
-# 📚 Search My Project Documentation
-
-**Primary terms:** authentication setup
-**Related terms:** login, auth, security  
-**Location:** docs
-
-## 🔍 Search Strategy
-
-1. **Start with Specific Terms**
-   Use your text search tools (grep, rg, ripgrep) to search for: `authentication setup`
 
-2. **Expand to Related Terms**  
-   If initial search doesn't yield results, try: `login, auth, security`
+### 2. Set Up Your First Docset
 
-3. **What to Avoid**
-   Skip these directories: `node_modules/`, `.git/`, `.knowledge/`
-```
-
-### 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  
-3. 🎯 Find exactly what you're looking for
-4. 🔗 Follow cross-references and related content
+**Option A: Use the CLI (Recommended)**
 
-## 💡 Pro Tips
+```bash
+# For a Git repository
+npx agentic-knowledge-mcp create \
+  --preset git-repo \
+  --id react-docs \
+  --name "React Documentation" \
+  --url https://github.com/facebook/react.git
 
-### Local Development Workflow
+# Initialize (downloads the docs)
+npx agentic-knowledge-mcp init react-docs
 
-```yaml
-# Perfect for active development
-docsets:
-  - id: current-project
-    name: Current Project
-    sources:
-      - type: local_folder
-        paths: ["./docs", "./README.md", "./CHANGELOG.md"]
+# The MCP server starts automatically when Claude Desktop launches
 ```
 
-**Benefits:**
-- Changes in your docs are immediately available
-- No copying or syncing needed
-- Works with any file type
+**Option B: Manual Configuration**
 
-### Multi-Repository Setup
+Create `.knowledge/config.yaml`:
 
 ```yaml
-# Combine multiple sources
+version: "1.0"
 docsets:
-  - id: frontend-docs
-    name: Frontend Documentation
+  - id: my-docs
+    name: My Project Documentation
     sources:
       - type: local_folder
-        paths: ["./frontend/docs"]
-      - type: git_repo
-        url: "https://github.com/company/design-system.git"
-        paths: ["docs/"]
-        
-  - id: backend-docs  
-    name: Backend Documentation
-    sources:
-      - type: git_repo
-        url: "https://github.com/company/api-docs.git"
-        branch: "main"
+        paths: ["./docs"]
 ```
 
-### Advanced Search Strategies
 
-Use specific and generalized keywords for better results:
+### 3. Use It
 
-```javascript
-// ✅ Good: Specific + General
-search_docs({
-  docset_id: "react-docs",
-  keywords: "useEffect cleanup function",
-  generalized_keywords: "hooks, lifecycle, memory management"
-})
+Your AI assistant now has access to `search_docs` and `list_docsets` tools. Ask questions naturally:
 
-// ❌ Too vague
-search_docs({
-  docset_id: "react-docs", 
-  keywords: "react",
-  generalized_keywords: "javascript"
-})
+```
+"How do I implement a cleanup function in React useEffect?"
+"Show me the authentication setup in our docs"
+"Find examples of rate limiting in the API docs"
 ```
 
-## 📊 Performance vs RAG
-
-| Metric             | Traditional RAG           | Agentic Knowledge |
-| ------------------ | ------------------------- | ----------------- |
-| **Setup Time**     | Hours (indexing)          | Seconds (config)  |
-| **Response Time**  | 300-2000ms                | <10ms             |
-| **Infrastructure** | Elasticsearch + Vector DB | Zero              |
-| **Maintenance**    | High (reindexing)         | None              |
-| **Accuracy**       | Fragment-based            | Complete context  |
-| **Cost**           | High (compute)            | Minimal           |
+The assistant will receive intelligent navigation instructions and use grep/file reading to find the exact information.
 
-## 🔬 The Future of Knowledge Systems
+## 📖 Documentation
 
-We're entering the **post-retrieval age**. The winners won't be those with the biggest vector databases, but those who design the smartest navigation systems for abundant context.
+- **[User Guide](./USER_GUIDE.md)** - Detailed CLI commands, lifecycle, configuration
+- **[Examples](./examples/)** - Configuration examples and integration guides
+- **[Testing Guide](./TESTING.md)** - Comprehensive testing documentation
 
-**RAG was training wheels**—useful, necessary, but temporary. The future belongs to systems that read, navigate, and reason end-to-end.
+## 💡 How and Why It Works
 
-## 🚀 Local Development & Installation
+### The Paradigm Shift
 
-### Installing from Source (Before NPM Publication)
+Traditional RAG (Retrieval-Augmented Generation) was built for the **context-poor era** when models had 8K token limits. It:
+- Chunks documents (losing relationships)
+- Computes embeddings (missing precise terminology)
+- Retrieves fragments (losing context)
+- Requires massive infrastructure (vector DBs, rerankers)
 
-Since the packages aren't published to npm yet, you can install them locally:
+**Agentic Knowledge** leverages modern AI capabilities:
+- ✅ **200K+ token context windows** - Can read entire documentation sets
+- ✅ **Powerful filesystem tools** - grep, ripgrep, file reading built-in
+- ✅ **Intelligent navigation** - Provides search strategies, not fragments
+- ✅ **Zero infrastructure** - Just a config file and your docs
 
-1. **Build all packages:**
+### From Retrieval to Navigation
 
-   ```bash
-   pnpm install
-   pnpm build
-   ```
+**Traditional RAG says:**
+*"Here are 50 fragments that mention your keywords"*
 
-2. **Create local installation packages:**
+**Agentic Knowledge says:**
+*"Search for 'useState' in `./docs/react-18.2/hooks/`. If that doesn't help, try 'state management' in `./docs/patterns/`. Follow any 'See also' references you find."*
 
-   ```bash
-   pnpm run pack:local
-   ```
+**The difference?** Guidance over fragments. Investigation over retrieval.
 
-   This creates `dist-local/` directory with packages that have workspace dependencies converted to relative file paths.
+### How It Actually Works
 
-3. **Install the MCP server locally:**
+1. **Configure docsets** - Point to local folders or Git repositories
+2. **Initialize** - Downloads/symlinks documentation to `.knowledge/docsets/`
+3. **MCP server** - Exposes `search_docs` and `list_docsets` tools
+4. **AI searches** - Gets navigation instructions, uses grep/file tools
+5. **Finds answers** - Reads complete documents with full context
 
-   ```bash
-   # Option 1: Install from tarball
-   cd dist-local/mcp-server && npm pack
-   npm install -g codemcp-knowledge-mcp-server-0.1.0.tgz
+**Performance:**
+- **Setup**: Seconds (vs hours for RAG indexing)
+- **Response**: <10ms (vs 300-2000ms for RAG)
+- **Infrastructure**: None (vs Elasticsearch + Vector DB)
+- **Accuracy**: Complete context (vs fragment-based)
 
-   # Option 2: Install directly from directory
-   npm install -g ./dist-local/mcp-server/
-   ```
+### Inspired By
 
-4. **Verify installation:**
-   ```bash
-   agentic-knowledge --help
-   ```
+This approach is inspired by [The RAG Obituary](https://www.nicolasbustamante.com/p/the-rag-obituary-killed-by-agents) by Nicolas Bustamante and how Claude Code revolutionized code analysis by ditching RAG for direct filesystem exploration.
 
-### Development
+## 🚀 Local Development
 
 ```bash
 # Install dependencies
@@ -492,27 +142,9 @@ pnpm test
 
 # Build all packages
 pnpm build
-
-# Format and lint
-pnpm format
-pnpm lint
 ```
 
-## 🧪 Development Status
-
-**Current Phase**: Finalization ✅
-
-- ✅ Core implementation complete (107 tests passing)
-- ✅ MCP protocol compliance verified
-- ✅ Performance validated (0.47ms response time)
-- ✅ Full documentation and examples
-- ⚠️ Ready for community feedback and real-world testing
-
-## 📚 Examples & Documentation
-
-- [`examples/`](./examples/) - Configuration examples and integration guides
-- [`TESTING.md`](./TESTING.md) - Comprehensive testing documentation
-- [Architecture docs](./.vibe/docs/) - Detailed technical specifications
+See [User Guide](./USER_GUIDE.md) for installation from source.
 
 ## 🤝 Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-knowledge-mcp",
-  "version": "0.1.13",
+  "version": "1.0.9",
   "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.9",
+    "@codemcp/knowledge-content-loader": "1.0.9",
+    "@codemcp/knowledge-mcp-server": "1.0.9"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "0.16.8",

package/packages/cli/dist/commands/create.js

@@ -107,7 +107,7 @@ async function createLocalFolderDocset(options) {
             throw new Error(`Path is not a directory: ${options.path}`);
         }
     }
-    catch (error) {
+    catch {
         throw new Error(`Path does not exist: ${options.path}`);
     }
     return {

package/packages/cli/dist/commands/status.js

@@ -114,40 +114,22 @@ function displaySummary(statuses) {
             continue;
         }
         if (!initialized) {
-            console.log(`${chalk.yellow("⚠️")} ${chalk.bold(docset.id)} - ${chalk.yellow("Not initialized")}`);
-            console.log(chalk.gray(`   ${docset.sources?.length || 0} source(s) configured`));
+            console.log(`${chalk.bold(docset.id)} (${docset.name})`);
+            console.log(chalk.gray(`   Not initialized | ${docset.sources?.length || 0} source(s) configured`));
+            console.log();
+            console.log(chalk.blue(`   💡 Run: agentic-knowledge init ${docset.id}`));
             continue;
         }
         if (!metadata) {
             console.log(`${chalk.red("❌")} ${chalk.bold(docset.id)} - ${chalk.red("Metadata corrupted")}`);
             continue;
         }
-        // Calculate status
-        const lastActivity = metadata.last_refreshed || metadata.initialized_at;
-        const lastActivityTime = new Date(lastActivity);
-        const timeSince = Date.now() - lastActivityTime.getTime();
-        const hoursSince = timeSince / (1000 * 60 * 60);
-        const daysSince = timeSince / (1000 * 60 * 60 * 24);
-        let timeDisplay;
-        let statusIcon;
-        if (hoursSince < 1) {
-            timeDisplay = `${Math.round(hoursSince * 60)} minutes ago`;
-            statusIcon = chalk.green("✅");
-        }
-        else if (hoursSince < 24) {
-            timeDisplay = `${Math.round(hoursSince)} hours ago`;
-            statusIcon = chalk.green("✅");
-        }
-        else if (daysSince < 7) {
-            timeDisplay = `${Math.round(daysSince)} days ago`;
-            statusIcon = chalk.yellow("⚠️");
-        }
-        else {
-            timeDisplay = `${Math.round(daysSince)} days ago`;
-            statusIcon = chalk.red("🔄");
-        }
-        console.log(`${statusIcon} ${chalk.bold(docset.id)} - ${chalk.gray(metadata.total_files)} files`);
-        console.log(chalk.gray(`   Last updated: ${timeDisplay} | ${sources.length}/${metadata.sources_count} sources loaded`));
+        // Format initialization date
+        const initDate = new Date(metadata.initialized_at);
+        const dateDisplay = initDate.toISOString().split("T")[0]; // YYYY-MM-DD format
+        console.log(`${chalk.bold(docset.id)} (${docset.name})`);
+        console.log(chalk.gray(`   Initialized | ${metadata.total_files} files | ${sources.length}/${metadata.sources_count} source(s) loaded`));
+        console.log(chalk.gray(`   Initialized: ${dateDisplay}`));
     }
 }
 function displayDetailedStatus(status) {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-cli",
-  "version": "0.1.13",
+  "version": "1.0.9",
   "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.9",
+    "@codemcp/knowledge-content-loader": "^1.0.9",
+    "@codemcp/knowledge-mcp-server": "^1.0.9",
     "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.9",
   "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
@@ -110,6 +108,8 @@ export interface TemplateContext {
 }
 /**
  * Error types that can occur in the core system
+ * Note: Linter may warn about "unused" enum values, but these are used throughout
+ * the codebase as ErrorType.CONFIG_NOT_FOUND, etc. The warnings are false positives.
  */
 export declare enum ErrorType {
     CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
@@ -130,7 +130,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

@@ -3,6 +3,8 @@
  */
 /**
  * Error types that can occur in the core system
+ * Note: Linter may warn about "unused" enum values, but these are used throughout
+ * the codebase as ErrorType.CONFIG_NOT_FOUND, etc. The warnings are false positives.
  */
 export var ErrorType;
 (function (ErrorType) {
@@ -29,31 +31,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.9",
   "description": "Core functionality for agentic knowledge guidance system",
   "type": "module",
   "main": "dist/index.js",

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

@@ -4,7 +4,9 @@
 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";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
 /**
  * Create an agentic knowledge MCP server
  * @returns MCP server instance
@@ -23,7 +25,7 @@ export function createAgenticKnowledgeServer() {
     let configLoadTime = 0;
     const CONFIG_CACHE_TTL = 60000; // 1 minute cache
     /**
-     * Load configuration with caching
+     * Load configuration with caching (returns null if no config found)
      */
     async function getConfiguration() {
         const now = Date.now();
@@ -34,7 +36,7 @@ export function createAgenticKnowledgeServer() {
             // Find configuration file path
             const configPath = await findConfigPath();
             if (!configPath) {
-                throw new Error("No configuration file found. Please create a .knowledge/config.yaml file in your project.");
+                return null; // No config file found - server can still start
             }
             // Load configuration
             const config = await loadConfig(configPath);
@@ -47,51 +49,70 @@ export function createAgenticKnowledgeServer() {
             // Clear cache on error to force retry next time
             configCache = null;
             configLoadTime = 0;
-            throw error;
+            // Return null instead of throwing - allow server to start
+            console.error("Error loading configuration:", error);
+            return null;
         }
     }
     // Register tool handlers
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        try {
-            // Load configuration to get available docsets
-            const { config } = await getConfiguration();
-            // Build rich description with available docsets
-            const docsetInfo = config.docsets
-                .map((docset) => {
-                const description = docset.description
-                    ? ` - ${docset.description}`
-                    : "";
-                return `• **${docset.id}** (${docset.name})${description}`;
-            })
-                .join("\n");
-            const searchDocsDescription = `Search for documentation in available docsets. Returns structured search strategy.
-
-📚 **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`;
+        // Load configuration to get available docsets
+        const configData = await getConfiguration();
+        // If no configuration, return tools with setup instructions
+        if (!configData) {
             return {
                 tools: [
                     {
                         name: "search_docs",
-                        description: searchDocsDescription,
+                        description: `Search for documentation in configured docsets. Returns structured response with search instructions and parameters.
+
+⚠️ **NO DOCSETS CONFIGURED**
+
+To configure docsets and use this tool:
+
+**Option 1: Use CLI (recommended)**
+\`\`\`bash
+# Create a docset for a Git repository
+agentic-knowledge create \\
+  --preset git-repo \\
+  --id my-docs \\
+  --name "My Documentation" \\
+  --url https://github.com/user/repo.git
+
+# Initialize it (downloads the docs)
+agentic-knowledge init my-docs
+
+# Restart the MCP server
+agentic-knowledge
+\`\`\`
+
+**Option 2: Manual configuration**
+Create \`.knowledge/config.yaml\`:
+\`\`\`yaml
+version: "1.0"
+docsets:
+  - id: my-docs
+    name: My Documentation
+    sources:
+      - type: local_folder
+        paths: ["./docs"]
+\`\`\`
+
+After configuring, the tool will show available docsets here.`,
                         inputSchema: {
                             type: "object",
                             properties: {
                                 docset_id: {
                                     type: "string",
-                                    description: "Choose the docset to search in.",
-                                    enum: config.docsets.map((d) => d.id),
+                                    description: "The identifier of the docset to search in. (No docsets configured - see tool description for setup instructions)",
                                 },
                                 keywords: {
                                     type: "string",
-                                    description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
+                                    description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting").',
                                 },
                                 generalized_keywords: {
                                     type: "string",
-                                    description: 'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
+                                    description: "Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target.",
                                 },
                             },
                             required: ["docset_id", "keywords"],
@@ -100,7 +121,7 @@ ${docsetInfo}
                     },
                     {
                         name: "list_docsets",
-                        description: "List all available documentation sets (docsets) with detailed information. Note: The search_docs tool already shows available docsets in its description, so this tool is mainly for getting additional metadata.",
+                        description: "List all available documentation sets (docsets) with detailed information. (Currently no docsets configured - see search_docs description for setup instructions)",
                         inputSchema: {
                             type: "object",
                             properties: {},
@@ -110,45 +131,66 @@ ${docsetInfo}
                 ],
             };
         }
-        catch (error) {
-            // Fallback to basic tools if configuration fails
-            return {
-                tools: [
-                    {
-                        name: "search_docs",
-                        description: "Search for documentation guidance based on keywords and context. Returns intelligent navigation instructions to help you find relevant information in a specific docset. (Configuration error - use list_docsets to see available options)",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                docset_id: {
-                                    type: "string",
-                                    description: "The identifier of the docset to search in. Use list_docsets to see available options.",
-                                },
-                                keywords: {
-                                    type: "string",
-                                    description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
-                                },
-                                generalized_keywords: {
-                                    type: "string",
-                                    description: 'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
-                                },
+        // Configuration exists - build rich description with available docsets
+        const { config } = configData;
+        const docsetInfo = config.docsets
+            .map((docset) => {
+            const description = docset.description
+                ? ` - ${docset.description}`
+                : "";
+            return `• **${docset.id}** (${docset.name})${description}`;
+        })
+            .join("\n");
+        const searchDocsDescription = `Search for documentation in available docsets. Returns structured response with search instructions and parameters.
+
+📚 **AVAILABLE DOCSETS:**
+${docsetInfo}
+
+🔍 **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: [
+                {
+                    name: "search_docs",
+                    description: searchDocsDescription,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            docset_id: {
+                                type: "string",
+                                description: "Choose the docset to search in.",
+                                enum: config.docsets.map((d) => d.id),
+                            },
+                            keywords: {
+                                type: "string",
+                                description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
+                            },
+                            generalized_keywords: {
+                                type: "string",
+                                description: 'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
                             },
-                            required: ["docset_id", "keywords"],
-                            additionalProperties: false,
                         },
+                        required: ["docset_id", "keywords"],
+                        additionalProperties: false,
                     },
-                    {
-                        name: "list_docsets",
-                        description: "List all available documentation sets (docsets) that can be searched. Each docset represents a specific project, library, or knowledge base.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {},
-                            additionalProperties: false,
-                        },
+                },
+                {
+                    name: "list_docsets",
+                    description: "List all available documentation sets (docsets) with detailed information. Note: The search_docs tool already shows available docsets in its description, so this tool is mainly for getting additional metadata.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                        additionalProperties: false,
                     },
-                ],
-            };
-        }
+                },
+            ],
+        };
     });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -164,32 +206,89 @@ ${docsetInfo}
                         throw new Error("keywords is required and must be a string");
                     }
                     // Load configuration
-                    const { config, configPath } = await getConfiguration();
+                    const configData = await getConfiguration();
+                    if (!configData) {
+                        throw new Error("No configuration file found.\n\n" +
+                            "To configure docsets:\n\n" +
+                            "**Option 1: Use CLI (recommended)**\n" +
+                            'agentic-knowledge create --preset git-repo --id my-docs --name "My Docs" --url <repo-url>\n' +
+                            "agentic-knowledge init my-docs\n\n" +
+                            "**Option 2: Manual configuration**\n" +
+                            "Create .knowledge/config.yaml in your project root.\n" +
+                            "See the search_docs tool description for example configuration.");
+                    }
+                    const { config, configPath } = configData;
                     // Find the requested docset
                     const docset = config.docsets.find((d) => d.id === docset_id);
                     if (!docset) {
                         const availableIds = config.docsets.map((d) => d.id).join(", ");
-                        throw new Error(`Docset '${docset_id}' not found. Available docsets: ${availableIds}`);
+                        throw new Error(`Docset '${docset_id}' not found.\n\n` +
+                            `Available docsets: ${availableIds}\n\n` +
+                            `To create a new docset:\n` +
+                            `agentic-knowledge create --preset git-repo --id ${docset_id} --name "My Docs" --url <repo-url>\n` +
+                            `agentic-knowledge init ${docset_id}`);
                     }
                     // Calculate local path
                     const localPath = calculateLocalPath(docset, configPath);
+                    // Check if docset is initialized by checking for metadata file
+                    const primarySource = docset.sources?.[0];
+                    if (primarySource?.type === "git_repo") {
+                        // For git repos, check if .agentic-metadata.json exists
+                        const configDir = dirname(configPath);
+                        const projectRoot = dirname(configDir);
+                        const absolutePath = resolve(projectRoot, localPath);
+                        const metadataPath = resolve(absolutePath, ".agentic-metadata.json");
+                        if (!existsSync(metadataPath)) {
+                            throw new Error(`Docset '${docset_id}' is not initialized.\n\n` +
+                                `The docset is configured but hasn't been initialized yet.\n\n` +
+                                `To initialize this docset:\n` +
+                                `agentic-knowledge init ${docset_id}\n\n` +
+                                `To check status of all docsets:\n` +
+                                `agentic-knowledge status`);
+                        }
+                    }
                     // Create template context with proper function signature
                     const templateContext = createTemplateContext(localPath, keywords.trim(), (generalized_keywords || "").trim(), docset);
                     // 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": {
                     // Load configuration
-                    const { config, configPath } = await getConfiguration();
+                    const configData = await getConfiguration();
+                    if (!configData) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "No docsets configured.\n\n" +
+                                        "To configure docsets:\n\n" +
+                                        "**Option 1: Use CLI (recommended)**\n" +
+                                        "```bash\n" +
+                                        'agentic-knowledge create --preset git-repo --id my-docs --name "My Docs" --url <repo-url>\n' +
+                                        "agentic-knowledge init my-docs\n" +
+                                        "```\n\n" +
+                                        "**Option 2: Manual configuration**\n" +
+                                        "Create `.knowledge/config.yaml`:\n" +
+                                        "```yaml\n" +
+                                        'version: "1.0"\n' +
+                                        "docsets:\n" +
+                                        "  - id: my-docs\n" +
+                                        "    name: My Documentation\n" +
+                                        "    sources:\n" +
+                                        "      - type: local_folder\n" +
+                                        '        paths: ["./docs"]\n' +
+                                        "```",
+                                },
+                            ],
+                        };
+                    }
+                    const { config, configPath } = configData;
                     // Return list of available docsets with calculated paths
                     const docsets = await Promise.all(config.docsets.map(async (docset) => ({
                         docset_id: docset.id,

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-mcp-server",
-  "version": "0.1.13",
+  "version": "1.0.9",
   "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.9",
     "@modelcontextprotocol/sdk": "^1.19.1"
   },
   "devDependencies": {