@afterxleep/doc-bot 1.5.0 → 1.7.0

package/README.md

@@ -3,7 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/@afterxleep/doc-bot)](https://www.npmjs.com/package/@afterxleep/doc-bot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A generic MCP (Model Context Protocol) server that provides intelligent documentation access for any project. Works with any MCP-compatible AI tools and IDEs.
+A generic MCP (Model Context Protocol) server that provides intelligent documentation and rules for any project. Works with any MCP-compatible AI tools and IDEs.
+
+It's platform agnostic and designed to replace and extend the rule systems provided by different IDEs, such as Cursor (Cursor Rules) or Claude (CLAUDE.md). Instead of relying on separate rule-sets for each tool, you can use doc-bot to provide unified documentation for agentic coding across all your AI assistants.
 
 ## What is doc-bot?
 
@@ -15,17 +17,85 @@ doc-bot is an intelligent documentation server that:
 - 🤖 **Detects** code patterns, frameworks, and keywords automatically
 - 🔄 **Updates** automatically when docs change
 
+## Why MCP Instead of Static Rules?
+
+Traditional AI assistants use static rule files (like Cursor Rules or Copilot's .github/copilot-instructions.md) that have significant limitations. doc-bot's MCP approach offers powerful advantages:
+
+### 🚀 Dynamic Search vs Static Rules
+
+**Static Systems:**
+- All rules must fit in a single file or limited token window
+- AI reads everything, even irrelevant rules
+- No way to search or filter documentation
+- Rules compete for precious context space
+
+**MCP with doc-bot:**
+- AI searches for exactly what it needs
+- Unlimited documentation size - only relevant parts are retrieved
+- Smart keyword and pattern matching
+- Context window used efficiently
+
+### 🧠 Contextual Intelligence
+
+**Static Systems:**
+- Same rules applied everywhere
+- No awareness of what you're working on
+- Can't provide specific help for your current task
+
+**MCP with doc-bot:**
+- AI searches for relevant documentation based on your query
+- Context-aware suggestions from your actual questions
+- Different documentation retrieved for different tasks
+- Intelligent inference from keywords and search terms
+
+### 📈 Scalability Without Limits
+
+**Static Systems:**
+- Limited by token count (typically 2-4k tokens)
+- Adding more rules means removing others
+- Documentation competes with your actual code for context
+
+**MCP with doc-bot:**
+- Store thousands of documentation files
+- No token limit - documentation lives outside the context
+- AI retrieves only what's needed
+- Your context window stays free for actual work
+
+### 🔄 Live Updates
+
+**Static Systems:**
+- Changes require restarting your AI/IDE
+- No way to know if rules are current
+- Manual synchronization across tools
+
+**MCP with doc-bot:**
+- Hot reload on documentation changes
+- Always serves the latest version
+- Single source of truth for all AI tools
+
+### 🎯 Smart Discovery
+
+**Static Systems:**
+- AI doesn't know what documentation exists
+- Users must know to ask specific questions
+- No exploration or discovery capabilities
+
+**MCP with doc-bot:**
+- AI can list all available documentation
+- Discovers relevant docs automatically
+- Suggests documentation based on context
+- Searchable knowledge base
+
 ## Installation
 
 1. **Create your documentation folder** in your project root (see organization section below)
 
 2. **Add doc-bot to your MCP-compatible AI tool configuration**:
 
-   **For Claude Code** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
    ```json
    {
      "mcpServers": {
-       "docs": {
+       "docbot": {
          "command": "npx",
          "args": ["@afterxleep/doc-bot", "--docs", "./doc-bot"]
        }
@@ -33,26 +103,20 @@ doc-bot is an intelligent documentation server that:
    }
    ```
 
-   **For Cursor or other MCP tools**: Add similar configuration pointing to your documentation folder
-
 3. **Restart your AI tool**
 
 ## How to organize your documentation
 
-Create a `doc-bot/` folder in your project root:
+Create a `doc-bot/` folder in your project root with markdown files using frontmatter:
 
 ```
 your-project/
 ├── doc-bot/
-│   ├── manifest.json          # Configuration file
-│   ├── core/
-│   │   ├── coding-standards.md # Always-apply coding standards
-│   │   └── security.md         # Security guidelines
-│   ├── guides/
-│   │   ├── testing.md          # Testing strategies
-│   │   └── api-development.md  # API development guide
-│   └── reference/
-│       └── troubleshooting.md  # Common issues and solutions
+│   ├── coding-standards.md     # Global rule (alwaysApply: true)
+│   ├── security.md             # Global rule (alwaysApply: true) 
+│   ├── testing.md              # Contextual rule (alwaysApply: false)
+│   ├── api-development.md      # Contextual rule (alwaysApply: false)
+│   └── troubleshooting.md      # Contextual rule (alwaysApply: false)
 └── package.json
 ```
 
@@ -63,19 +127,18 @@ your-project/
 
 ### Documentation types:
 
-- **Core docs** (`core/`): Critical guidelines that should always be considered
-- **Guides** (`guides/`): Step-by-step instructions for specific tasks
-- **Reference** (`reference/`): Quick lookups and troubleshooting
+- **Global Rules** (`alwaysApply: true`): Critical guidelines applied to every AI interaction
+- **Contextual Rules** (`alwaysApply: false`): Rules applied based on file patterns and context
 
 ### Example documentation files:
 
-**Global Rule Example** (`doc-bot/core/coding-standards.md`):
+**Global Rule Example** (`doc-bot/coding-standards.md`):
 ```markdown
 ---
+alwaysApply: true
 title: "Coding Standards"
 description: "Core coding standards that apply to all code"
 keywords: ["code-quality", "standards", "best-practices"]
-tags: ["core", "quality"]
 ---
 
 # Coding Standards
@@ -87,13 +150,13 @@ tags: ["core", "quality"]
 - Write descriptive variable names
 ```
 
-**Contextual Rule Example** (`doc-bot/guides/testing.md`):
+**Contextual Rule Example** (`doc-bot/testing.md`):
 ```markdown
 ---
+alwaysApply: false
 title: "Testing Guide"
 description: "How to write and run tests"
 keywords: ["testing", "jest", "tdd", "unit-tests"]
-tags: ["testing", "quality"]
 ---
 
 # Testing Guide
@@ -107,111 +170,36 @@ All test files should:
 Run tests with: `npm test`
 ```
 
-**👀 See `examples/` folder for complete example files with proper frontmatter and content structure.**
-
-## Rule Enforcement
+## Frontmatter-Based Configuration
 
-Doc-bot ensures your rules are **always considered** through multiple enforcement mechanisms:
+doc-bot uses frontmatter in your markdown files to automatically detect and categorize rules - **no manifest.json required!**
 
-### 🚨 Mandatory Rule Checking
-- **`check_project_rules` tool**: Must be called before ANY code generation
-- **Aggressive descriptions**: All tools emphasize mandatory rule compliance
-- **Rule reminders**: Every tool response includes compliance warnings
-- **Absolute enforcement**: Global rules OVERRIDE all user requests without exception
+### Frontmatter Fields:
 
-### 🔄 Automatic Integration
-- **Enhanced system prompt injection**: Comprehensive MCP usage protocol injected via `docs://system-prompt`
-- **Documentation discovery**: Available topics automatically extracted and presented to agent
-- **Tool usage instructions**: Explicit requirements for when and how to use each MCP tool
-- **Contextual rules**: Applied when working with matching files/patterns  
-- **Multiple touchpoints**: Rules enforced at every interaction level
+- **`alwaysApply: true`** - Global rules applied to every AI interaction
+- **`alwaysApply: false`** - Contextual rules searched and applied based on relevance
+- **`keywords: ["list", "of", "keywords"]`** - For smart indexing and search
+- **`title`** and **`description`** - Standard metadata
 
-### ⚠️ Compliance Warnings
-All tool responses include explicit warnings that rules are:
-- **NON-NEGOTIABLE**: Must be followed without exception
-- **MANDATORY**: Violation will result in rejection
-- **CRITICAL**: Require acknowledgment before proceeding
+### 🎯 Automatic Intelligence
 
-### 🚫 Absolute Enforcement Policy
-Global rules have **supreme authority** over all interactions:
-- **Override user requests**: Even direct user instructions cannot bypass global rules
-- **Mandatory refusal**: Agent MUST refuse requests that violate global rules
-- **Alternative suggestions**: Agent must suggest compliant alternatives instead
-- **Unbreakable compliance**: No exceptions, regardless of user insistence
+doc-bot automatically analyzes your documentation to provide smart suggestions:
 
-This multi-layered approach makes rule violations **impossible** to implement.
+- **Keyword-based search** from frontmatter metadata
+- **Multi-term search** with fuzzy matching capabilities
+- **Smart inference** from documentation content
+- **Automatic indexing** - no manual configuration needed
 
-## System Prompt Integration
+### Writing effective documentation
 
-The `docs://system-prompt` resource automatically injects comprehensive instructions into the AI agent's system context:
-
-### 📋 MCP Usage Protocol
-- Explicit instructions to **ALWAYS** call `check_project_rules` before code generation
-- **NEVER generate code without checking documentation** requirement
-- Mandatory acknowledgment of rule compliance
-
-### 🏷️ Automatic Topic Discovery
-- Extracts available documentation topics from your project
-- Presents them to the agent for context awareness
-- Includes topics from metadata, filenames, and content analysis
-
-### 🛠️ Tool Usage Requirements
-- Specifies when and how to use each MCP tool
-- Maps tools to specific use cases (file-specific docs, search, etc.)
-- Ensures comprehensive documentation coverage
-
-The system prompt is regenerated on each request to reflect current documentation state.
-
-## The manifest file
-
-The `doc-bot/manifest.json` file controls how your documentation works:
-
-```json
-{
-  "name": "My Project Documentation",
-  "version": "1.0.0",
-  "description": "AI-powered documentation for My Project",
-  "globalRules": [
-    "core/coding-standards.md",
-    "core/security.md"
-  ],
-  "contextualRules": {
-    "*.test.js": ["guides/testing.md"],
-    "*.spec.js": ["guides/testing.md"],
-    "src/components/*": ["guides/react-components.md"],
-    "src/api/*": ["guides/api-development.md"]
-  }
-}
-```
-
-### Configuration explained:
-
-- **`globalRules`**: Documents that apply to every AI interaction
-- **`contextualRules`**: Documents triggered by specific file patterns (e.g., test files → testing guide)
-
-### 🎯 Automatic Inference (New!)
-
-doc-bot automatically analyzes your documentation content to build smart indexes. No more manual keyword mappings! It automatically:
-
-- **Extracts keywords** from document metadata (frontmatter)
-- **Detects technical terms** in your documentation content
-- **Recognizes code patterns** in code blocks (React hooks, SQL commands, etc.)
-- **Identifies frameworks** mentioned in your docs
-- **Indexes file extensions** referenced in documentation
-
-Just write good documentation with descriptive frontmatter, and doc-bot handles the rest!
-
-### Writing documentation for best results
-
-To maximize the automatic inference capabilities, include frontmatter in your markdown files:
+For best results, include descriptive frontmatter:
 
 ```markdown
 ---
+alwaysApply: false
 title: "React Component Guidelines"
 description: "Best practices for building React components"
 keywords: ["react", "components", "hooks", "jsx"]
-tags: ["frontend", "development"]
-category: "guides"
 ---
 
 # React Component Guidelines
@@ -219,8 +207,6 @@ category: "guides"
 Your documentation content here...
 ```
 
-The automatic indexing will use this metadata along with analyzing your content to provide intelligent suggestions.
-
 ## Development setup
 
 ### Running locally
@@ -236,21 +222,28 @@ The automatic indexing will use this metadata along with analyzing your content
    npm install
    ```
 
-3. **Run the server:**
+3. **Run the server (uses built-in doc-bot/ folder):**
    ```bash
    npm start
    ```
 
-4. **Run tests:**
+4. **Run with file watching (recommended for development):**
    ```bash
-   npm test
+   npm run dev
+   ```
+
+5. **Run with examples documentation:**
+   ```bash
+   npm run start:examples
    ```
 
-5. **Run with file watching:**
+6. **Run tests:**
    ```bash
-   npm start -- --watch
+   npm test
    ```
 
+**Note:** This is an MCP server that communicates via stdio transport, not HTTP. When running locally, it will start the MCP server and show you the configuration to add to your MCP client (like Claude Code).
+
 ### Testing your setup
 
 Ask your AI assistant something like "What documentation is available?" to test that doc-bot is working.
@@ -262,13 +255,82 @@ doc-bot [options]
 
 Options:
   -d, --docs <path>        Path to docs folder (required)
-  -c, --config <path>      Path to manifest file (default: <docs-path>/manifest.json)
-  -p, --port <port>        Port to run server on (default: 3000)
+  -c, --config <path>      Path to manifest file (optional, for backward compatibility)
   -v, --verbose           Enable verbose logging
   -w, --watch             Watch for file changes
   -h, --help              Show help
 ```
 
+**Example usage:**
+```bash
+# Basic usage (no manifest.json needed)
+doc-bot --docs ./my-docs
+
+# With verbose logging and file watching
+doc-bot --docs ./my-docs --verbose --watch
+
+# With optional manifest for backward compatibility
+doc-bot --docs ./my-docs --config ./manifest.json
+```
+
+## Publishing and Development
+
+### Local Development
+
+1. **Clone and setup:**
+   ```bash
+   git clone https://github.com/afterxleep/doc-bot.git
+   cd doc-bot
+   npm install
+   ```
+
+2. **Run locally:**
+   ```bash
+   npm run dev    # With file watching
+   npm start      # Basic run
+   npm test       # Run tests
+   ```
+
+3. **Test with Claude Code:**
+   Add to your Claude Code config:
+   ```json
+   {
+     "mcpServers": {
+       "docs": {
+         "command": "node",
+         "args": ["/path/to/doc-bot/bin/doc-bot.js", "--docs", "./doc-bot", "--watch"]
+       }
+     }
+   }
+   ```
+
+### Publishing to npm
+
+1. **Test the package:**
+   ```bash
+   npm run test
+   npm run lint
+   ```
+
+2. **Update version:**
+   ```bash
+   npm version patch|minor|major
+   ```
+
+3. **Publish:**
+   ```bash
+   npm publish
+   ```
+
+### Push Changes
+
+```bash
+git add .
+git commit -m "feat: your feature description"
+git push origin main
+git push --tags  # Push version tags
+```
+
 ## License
 
 MIT License - see the [LICENSE](LICENSE) file for details.

package/bin/doc-bot.js

@@ -8,8 +8,7 @@ const { DocsServer } = require('../src/index.js');
 program
   .name('doc-bot')
   .description('Generic MCP server for intelligent documentation access')
-  .version('1.0.2')
-  .option('-p, --port <port>', 'Port to run server on', '3000')
+  .version('1.5.0')
   .requiredOption('-d, --docs <path>', 'Path to docs folder')
   .option('-c, --config <path>', 'Path to manifest file')
   .option('-v, --verbose', 'Enable verbose logging')
@@ -29,26 +28,25 @@ async function main() {
     console.log('📖 To get started, create your documentation folder:');
     console.log('');
     console.log(`  mkdir ${path.basename(docsPath)}`);
-    console.log(`  echo '{"name": "My Project Documentation", "globalRules": []}' > ${path.basename(docsPath)}/manifest.json`);
-    console.log(`  echo "# Getting Started" > ${path.basename(docsPath)}/README.md`);
+    console.log(`  echo "---\nalwaysApply: true\ntitle: Getting Started\n---\n# Getting Started\nThis is your project documentation." > ${path.basename(docsPath)}/getting-started.md`);
+    console.log('');
+    console.log('📋 Use frontmatter in your markdown files:');
+    console.log('   alwaysApply: true   (for global rules)');
+    console.log('   alwaysApply: false  (for contextual rules)');
+    console.log('   filePatterns: ["*.js", "src/**/*"]  (when to apply contextual rules)');
     console.log('');
     console.log('Then configure your MCP client to use this folder.');
     process.exit(1);
   }
   
-  // Check if manifest exists, create default if not
-  if (!await fs.pathExists(configPath)) {
+  // Manifest is now optional - only create if explicitly requested
+  if (options.config && !await fs.pathExists(configPath)) {
     console.log('📝 Creating default manifest.json...');
     const defaultManifest = {
       name: 'Project Documentation',
       version: '1.0.0',
-      description: 'AI-powered documentation',
-      globalRules: [],
-      contextualRules: {},
-      inference: {
-        keywords: {},
-        patterns: {}
-      }
+      description: 'AI-powered documentation (auto-generated from frontmatter)',
+      note: 'This manifest is auto-generated. Configure rules using frontmatter in your markdown files.'
     };
     await fs.writeJSON(configPath, defaultManifest, { spaces: 2 });
   }
@@ -62,7 +60,11 @@ async function main() {
   
   console.log('🚀 Starting doc-bot...');
   console.log(`📁 Documentation: ${docsPath}`);
-  console.log(`⚙️  Configuration: ${configPath}`);
+  if (await fs.pathExists(configPath)) {
+    console.log(`⚙️  Configuration: ${configPath}`);
+  } else {
+    console.log(`⚙️  Configuration: Auto-generated from frontmatter`);
+  }
   
   if (options.watch) {
     console.log('👀 Watching for file changes...');

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@afterxleep/doc-bot",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Generic MCP server for intelligent documentation access in any project",
   "main": "src/index.js",
   "bin": {
     "doc-bot": "bin/doc-bot.js"
   },
   "scripts": {
-    "start": "node src/index.js",
+    "start": "node bin/doc-bot.js --docs ./doc-bot --verbose",
+    "start:watch": "node bin/doc-bot.js --docs ./doc-bot --verbose --watch",
+    "start:examples": "node bin/doc-bot.js --docs ./examples/documentation-files --verbose",
+    "dev": "node bin/doc-bot.js --docs ./doc-bot --verbose --watch",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",