@afterxleep/doc-bot 1.5.0 → 1.6.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?
 
@@ -21,11 +23,10 @@ doc-bot is an intelligent documentation server that:
 
 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 +34,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 +58,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 +81,14 @@ 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"]
+filePatterns: ["*.js"]
 ---
 
 # Testing Guide
@@ -107,111 +102,38 @@ All test files should:
 Run tests with: `npm test`
 ```
 
-**👀 See `examples/` folder for complete example files with proper frontmatter and content structure.**
-
-## Rule Enforcement
-
-Doc-bot ensures your rules are **always considered** through multiple enforcement mechanisms:
-
-### 🚨 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
-
-### 🔄 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
-
-### ⚠️ 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
-
-### 🚫 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
-
-This multi-layered approach makes rule violations **impossible** to implement.
-
-## System Prompt Integration
-
-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
+## Frontmatter-Based Configuration
 
-The `doc-bot/manifest.json` file controls how your documentation works:
+doc-bot uses frontmatter in your markdown files to automatically detect and categorize rules - **no manifest.json required!**
 
-```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:
+### Frontmatter Fields:
 
-- **`globalRules`**: Documents that apply to every AI interaction
-- **`contextualRules`**: Documents triggered by specific file patterns (e.g., test files → testing guide)
+- **`alwaysApply: true`** - Global rules applied to every AI interaction
+- **`alwaysApply: false`** - Contextual rules applied based on file patterns
+- **`filePatterns: ["*.js"]`** - When to apply contextual rules (only needed for `alwaysApply: false`)
+- **`keywords: ["list", "of", "keywords"]`** - For smart indexing and search
+- **`title`** and **`description`** - Standard metadata
 
-### 🎯 Automatic Inference (New!)
+### 🎯 Automatic Intelligence
 
-doc-bot automatically analyzes your documentation content to build smart indexes. No more manual keyword mappings! It automatically:
+doc-bot automatically analyzes your documentation to provide smart suggestions:
 
-- **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
+- **Keyword-based search** from frontmatter metadata
+- **Context-aware suggestions** based on file patterns
+- **Smart inference** from documentation content
+- **Automatic indexing** - no manual configuration needed
 
-Just write good documentation with descriptive frontmatter, and doc-bot handles the rest!
+### Writing effective documentation
 
-### 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"
+filePatterns: ["*.js"]
 ---
 
 # React Component Guidelines
@@ -219,8 +141,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 +156,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 file watching:**
+5. **Run with examples documentation:**
    ```bash
-   npm start -- --watch
+   npm run start:examples
    ```
 
+6. **Run tests:**
+   ```bash
+   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 +189,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.6.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",