Docsgrep

npm version license MCP compatible

docsgrep is a developer tool for documentation search, code quality auditing, security scanning, and bug detection. Run it from the command line during development, or integrate it as an MCP server for AI-assisted coding workflows.

---

Table of Contents

• Features
• Quick Start
• Installation
• CLI Usage
• MCP Server
• Tools
  • Discovery & Setup
  • Content & Search
  • Auditing & Quality
  • Maintenance & Sync
  • Context & Help
• Plugin System
• Developer Guide
• Architecture
• Security
• Contributing
• License

---

Features

• Documentation Intelligence -- Semantic search, summarization, and topic-based discovery across your docs.
• Code Quality Auditing -- Enterprise-grade audits with code smell detection, convention analysis, and quality scoring.
• Security Scanning -- OWASP Top 10 coverage, secret/credential detection, PII scanning, and dependency vulnerability auditing.
• Bug Detection -- Runtime error detection, race condition analysis, memory leak identification, and performance issue discovery.
• Architectural Analysis -- Pattern detection (MVC, Repository, etc.), dependency mapping, and refactoring candidate identification.
• Documentation Integrity -- Staleness detection, coverage measurement, doc-vs-code delta analysis, and automated sync.
• Remote Repository Support -- Clone and analyze remote repositories with smart caching and authentication (HTTPS, SSH).
• Plugin System -- Extend docsgrep with community or custom plugins via docsgrep-plugin-* packages.

---

Quick Start

# Run without installing
npx docsgrep run analyze_code

# Or install globally
npm install -g docsgrep
docsgrep run audit_security --format json

Run show_help for a full list of available tools:

npx docsgrep run show_help

---

Installation

Global install

npm install -g docsgrep

Local install (per-project)

npm install --save-dev docsgrep

Run without installing

npx docsgrep run <tool_name> [--param value]

Requirements

• Node.js >= 18
• pnpm (recommended), npm, or yarn

---

CLI Usage

docsgrep run <tool_name> [--param value ...] [--format text|json]

Arguments

Flag	Description
--format text	Plain text output (default)
--format json	Pretty-printed JSON output
--dirPath <path>	Target directory (defaults to cwd)
--pattern <regex>	Search pattern for search_docs
--topK <n>	Number of results for semantic_search
--maxAgeDays <n>	Staleness threshold in days
Comma-separated values	Automatically parsed as arrays (e.g., --filePatterns "*.ts,*.js")

Examples

# Code quality audit on the current directory
npx docsgrep run analyze_code

# Security scan with JSON output
npx docsgrep run audit_security --format json

# Regex search in documentation
npx docsgrep run search_docs --pattern "authentication" --contextLines 2

# Detect bugs and potential runtime errors
npx docsgrep run catch_bugs --dirPath ./src

# Semantic search for documentation
npx docsgrep run semantic_search --query "how to handle errors" --topK 5

# Find docs related to a topic
npx docsgrep run find_related --topic "database migration"

# Measure documentation coverage
npx docsgrep run measure_coverage --publicOnly true

# Detect project technology stack
npx docsgrep run detect_stack

# Check for stale documentation
npx docsgrep run check_stale --maxAgeDays 30

# Clone and analyze a remote repo
npx docsgrep run clone_repo --repoUrl https://github.com/user/repo

npm Script Shortcuts

When docsgrep is installed locally, these shortcuts are available:

Script	Runs
npm run lint	analyze_code -- code quality audit
npm run audit	audit_security -- security audit
npm run bugs	catch_bugs -- bug detection
npm run docs:check	measure_coverage -- doc coverage
npm run docs:stale	check_stale -- stale doc detection

---

MCP Server

docsgrep functions as a Model Context Protocol (MCP) server, giving AI agents and MCP-compatible IDEs access to all 25 tools.

Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "docsgrep": {
      "command": "npx",
      "args": ["-y", "docsgrep"]
    }
  }
}

OpenCode

Already configured via opencode.json in this repository:

{
  "mcp": {
    "docsgrep": {
      "type": "local",
      "command": ["npx", "tsx", "src/index"]
    }
  }
}

Local Development (from source)

{
  "mcpServers": {
    "docsgrep": {
      "command": "npx",
      "args": ["tsx", "src/index"]
    }
  }
}

How It Works

1. On startup, docsgrep initializes the tool registry and discovers any installed plugins.
2. When an MCP client connects, it lists all available tools (core + plugin tools).
3. When a tool is called, docsgrep validates inputs, executes the handler, and returns a structured McpToolResponse.
4. The server communicates over stdio transport.

---

Tools

docsgrep ships with 25 tools organized into five categories.

Discovery & Setup

Tool	Description	Key Arguments
init_workspace	Initialize a docsgrep workspace (.docsgrep/) and update .gitignore	projectPath
detect_stack	Identify project technology stack from package manager files	dirPath
check_style	Detect coding conventions and implicit patterns from codebase samples	dirPath
find_docs	Discover README files and documentation folders	dirPath, includePath, excludePath
clone_repo	Clone a remote git repository with caching and auth support	repoUrl, branch, authToken, sshKeyPath

Content & Search

Tool	Description	Key Arguments
read_file	Read a documentation file with binary detection	filePath
search_docs	Regex search with relevance ranking and context lines	dirPath, pattern, contextLines
semantic_search	Natural language search across documentation	dirPath, query, topK
summarize_doc	Automatic summarization of a documentation file	filePath, maxLength

Auditing & Quality

Tool	Description	Key Arguments
analyze_code	Full code quality audit with scoring and recommendations	dirPath, focusAreas, includePath
audit_security	OWASP Top 10, secret scanning, PII analysis, dependency audit	dirPath, includePath
catch_bugs	Detect runtime errors, race conditions, memory leaks, logic flaws	dirPath, includePath
lint_interactive	Interactive prompt showing detected stack and linting options	dirPath
security_interactive	Interactive prompt showing scan options before execution	dirPath

Maintenance & Sync

Tool	Description	Key Arguments
check_stale	Identify documentation not updated in N days or out of sync with code	dirPath, maxAgeDays, compareWithCode
measure_coverage	Measure docblock coverage across source code (language-agnostic)	dirPath, publicOnly, filePatterns
sync_documentation	Generate or update documentation stubs from code changes	dirPath, filePaths, updateMode
verify_docs	Verify documented methods/params match actual implementation	dirPath, docPath, strictMode
check_delta	Compare documentation claims against code reality	dirPath, docPath, includeCodeSnippets
check_artefacts	Prioritize documentation updates from git diff history	dirPath, sinceCommit, priorityMode

Context & Help

Tool	Description	Key Arguments
get_context	Proactively provide relevant docs based on current file context	dirPath, currentFilePath, contextDepth
show_help	In-app help for all tools with examples and pro tips	toolName (optional)
clear_cache	Clean cached repositories older than N days	localProjectPath, maxAgeDays

---

Plugin System

docsgrep supports plugins that add custom tools to the CLI and MCP server.

Installing Plugins

Plugins are discovered automatically from node_modules:

# Install a plugin
npm install docsgrep-plugin-laravel

# It's now available as a tool
npx docsgrep run laravel_check_relations

Plugin Naming Convention

• docsgrep-plugin-<name> -- auto-discovered
• @docsgrep/plugin-<name> -- auto-discovered
• Any path/package listed in docsgrep.config.json -- explicit

Writing a Plugin

A plugin is an ESM module that default-exports a DocsgrepPlugin object:

import type { DocsgrepPlugin } from "docsgrep";

const plugin: DocsgrepPlugin = {
  name: "my-plugin",
  version: "1.0.0",
  tools: {
    definitions: [
      {
        name: "my_custom_tool",
        description: "Does something custom",
        inputSchema: {
          type: "object",
          properties: {
            dirPath: { type: "string", description: "Target directory" },
          },
          required: ["dirPath"],
        },
      },
    ],
    handlers: {
      my_custom_tool: async (args) => {
        return {
          content: [{ type: "text", text: JSON.stringify({ result: "done" }) }],
        };
      },
    },
  },
  onLoad: async () => {
    console.log("My plugin loaded!");
  },
};

export default plugin;

See docs/PLUGIN_GUIDE.md for the full guide.

---

Developer Guide

Prerequisites

• pnpm >= 9.0
• Node.js >= 18

Setup

git clone https://github.com/reasvyn/docsgrep.git
cd docsgrep
pnpm install

Common Commands

Command	Description
pnpm build	Compile TypeScript to build/
pnpm dev	Run from source via tsx
pnpm test	Run all Vitest tests
pnpm test:coverage	Run tests with V8 coverage report
pnpm lint	Run analyze_code on itself (dogfooding)
pnpm audit	Run audit_security on itself
pnpm bugs	Run catch_bugs on itself
pnpm docs:check	Run measure_coverage on itself
pnpm docs:stale	Run check_stale on itself

Note: The lint, audit, bugs, docs:check, and docs:stale scripts run docsgrep on its own source code. They require pnpm build first.

Running a Single Test

pnpm vitest run tests/unit/tools/documentation.test.ts

Project Structure

docsgrep/
├── src/
│   ├── index.ts            # Entry point (MCP server + plugin discovery)
│   ├── cli.ts              # CLI argument parsing and display
│   ├── core-tools.ts       # Class-based tools (AnalyzeCodeTool, etc.)
│   ├── tools/              # Tool handlers (one module per logical group)
│   │   ├── base.ts         # BaseTool<T> abstract class
│   │   ├── registry.ts     # Tool registry (name → handler mapping)
│   │   ├── doc-find.ts     # find_docs
│   │   ├── doc-search.ts   # search_docs, semantic_search, find_related
│   │   ├── doc-inspect.ts  # read_file, summarize_doc, check_stale, get_context
│   │   ├── doc-coverage.ts # measure_coverage
│   │   ├── doc-verify.ts   # verify_docs, check_delta
│   │   ├── doc-sync.ts     # sync_documentation, check_artefacts
│   │   ├── help.ts         # show_help
│   │   ├── repo-analysis.ts # detect_stack, check_style
│   │   ├── repo.ts         # clone_repo
│   │   ├── workspace.ts    # init_workspace, clear_cache
│   │   ├── archetypes.ts   # detect_patterns
│   │   └── audit-ask.ts    # lint_interactive, security_interactive
│   ├── utils/              # Shared utilities
│   │   ├── file.ts         # FileScanner, getIgnorePatterns
│   │   ├── git.ts          # Git operations + repo cache
│   │   ├── validation.ts   # Input validation
│   │   ├── semaphore.ts    # Concurrency limiter
│   │   ├── logger.ts       # Dual output: stderr + file logs
│   │   ├── workspace.ts    # .docsgrep/ path resolution
│   │   ├── cache.ts        # TTL-based file cache
│   │   ├── plugin-manager.ts
│   │   └── app-info.ts     # AppInfo (version, name from package.json)
│   ├── types/              # TypeScript interfaces
│   │   ├── tools.ts        # McpToolResponse + all tool arg interfaces
│   │   └── plugins.ts      # DocsgrepPlugin interface
│   └── config/             # JSON configuration
│       ├── tools.json      # MCP tool definitions (JSON Schema)
│       ├── patterns.json
│       └── *.json          # Per-language configs (js, py, go, rs, etc.)
├── tests/
│   ├── unit/               # Unit tests (vi.mock for IO)
│   └── integration/        # E2E tests (StdioClientTransport)
├── docs/
│   ├── overview.md         # Project overview
│   ├── architecture.md     # System design
│   ├── requirements.md     # Runtime prerequisites
│   ├── conventions.md      # Coding standards
│   ├── index.md            # Documentation index
│   ├── README.md           # Tool documentation index
│   ├── PLUGIN_GUIDE.md     # Plugin authoring guide
│   └── tools/              # Per-tool documentation (*.md)
├── plugins/                # Local plugin directory
├── scripts/                # Build/publish scripts
├── .agents/                # OpenCode agent skills
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── AGENTS.md               # AI agent instructions
└── opencode.json           # OpenCode MCP config

Architecture Notes

• ESM-only: all local imports must include the .js extension.
• BaseTool pattern: tool handlers extend BaseTool<T> for concurrency control, logging, credential masking, and error wrapping.
• ToolRegistry: static class mapping tool names to handler functions. Falls back to PluginManager for plugin tools.
• Input validation: every handler validates dirPath with validateDirPath and string params with validateStringParam.
• FileScanner: all filesystem scanning goes through FileScanner.findFiles() which respects .gitignore, includePath, and excludePath.
• Concurrency: a Semaphore(5) limits parallel operations via operationLimiter in BaseTool.
• App metadata: always use AppInfo from utils/app-info.ts -- never hardcode version or name.

---

Security

• Path traversal prevention: all file operations resolve against strict base paths.
• Credential masking: BaseTool automatically redacts authToken fields in logs. New sensitive params must be added to maskSensitive.
• No secret leakage: credentials are detected but never logged or included in responses.
• Concurrency protection: built-in semaphore prevents system saturation from parallel tool execution.
• Binary detection: binary files are automatically detected and skipped during scanning.

---

Contributing

See CONTRIBUTING.md for setup instructions, coding conventions, and PR expectations.

Quick Reference

1. pnpm install -- install dependencies
2. Create a feature branch
3. Write code + tests
4. pnpm build && pnpm test -- verify
5. Open a PR with a clear description of intent and impact

---

License

MIT -- Copyright (c) 2026 Reasvyn