@devista/docs-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,17 @@
 # @devista/docs-mcp
 
-A generic MCP server that provides full-text search over Markdown/MDX documentation folders. Point it at any docs directory and AI agents (Claude Code, etc.) can search, browse, and read your documentation.
+A generic MCP server that gives AI agents (Claude Code, Cursor, etc.) full-text search over any Markdown/MDX documentation folder. Point it at your docs and your AI assistant can search, browse, and read your project documentation during development.
+
+## How It Works
+
+The server runs as a local process communicating over stdio (the standard MCP transport). When it starts:
+
+1. **Freshness check** — compares modification times of your doc files against the last-built index
+2. **Auto-rebuild** — if any file changed (or the index doesn't exist yet), it parses all Markdown/MDX files, strips MDX syntax (imports, JSX component tags), extracts frontmatter, and builds a [Flexsearch](https://github.com/nextapps-de/flexsearch) full-text search index
+3. **Serve** — exposes three MCP tools (`search_docs`, `get_page`, `list_sections`) that agents can call to query your documentation
+4. **Cached** — the index is stored in `.docs-mcp/` in your working directory, so subsequent startups are instant if nothing changed
+
+The server understands standard Markdown frontmatter (`title`, `description`) and organizes pages into sections based on directory structure (e.g. `backend/payments.md` belongs to the `backend` section).
 
 ## Quick Start
 
@@ -17,20 +28,89 @@ Add to your project's `.mcp.json`:
 }
 ```
 
-That's it. The server will index your docs on first start and auto-rebuild when files change.
+That's it. Restart your AI tool and the docs are queryable.
 
-## Configuration
+## Usage Examples
 
-### CLI Args
+### Relative path — docs inside your project
 
-| Arg | Description |
-|-----|-------------|
-| `--docs <path>` | Path to documentation folder (required) |
-| `--name <name>` | Server name shown in MCP clients (default: `docs-mcp`) |
+When your documentation lives alongside your code:
+
+```
+my-project/
+├── src/
+├── docs/           <-- your markdown docs
+├── .mcp.json
+└── package.json
+```
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
+    }
+  }
+}
+```
+
+### Relative path — Astro/Starlight project
+
+For documentation sites using Astro Starlight:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp", "--docs", "./src/content/docs"]
+    }
+  }
+}
+```
 
-### Config File
+### Absolute path — docs in a separate repo or folder
 
-Create `.docs-mcp.json` in your project root for persistent settings:
+When your docs live outside the current project (e.g. a monorepo or a separate docs repo):
+
+```json
+{
+  "mcpServers": {
+    "project-docs": {
+      "command": "npx",
+      "args": [
+        "-y", "@devista/docs-mcp",
+        "--docs", "/Users/me/projects/my-docs/src/content/docs",
+        "--name", "project-docs"
+      ]
+    }
+  }
+}
+```
+
+### Multiple documentation sources
+
+You can register multiple instances for different doc folders:
+
+```json
+{
+  "mcpServers": {
+    "api-docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/api", "--name", "api-docs"]
+    },
+    "architecture-docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/architecture", "--name", "architecture-docs"]
+    }
+  }
+}
+```
+
+### Using a config file instead of CLI args
+
+Create `.docs-mcp.json` in your project root:
 
 ```json
 {
@@ -41,7 +121,7 @@ Create `.docs-mcp.json` in your project root for persistent settings:
 }
 ```
 
-CLI args override config file values. When using a config file, your `.mcp.json` simplifies to:
+Then your `.mcp.json` simplifies to:
 
 ```json
 {
@@ -54,42 +134,49 @@ CLI args override config file values. When using a config file, your `.mcp.json`
 }
 ```
 
-### Defaults
+## Configuration
+
+### CLI Args
+
+| Arg | Description |
+|-----|-------------|
+| `--docs <path>` | Path to documentation folder (required unless set in config file) |
+| `--name <name>` | Server name shown in MCP clients (default: `docs-mcp`) |
+
+### Config File (`.docs-mcp.json`)
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `docs` | string | — | Path to documentation folder (required) |
+| `include` | string[] | `["**/*.md", "**/*.mdx"]` | Glob patterns for files to index |
+| `exclude` | string[] | `["**/node_modules/**"]` | Glob patterns for files to skip |
+| `name` | string | `docs-mcp` | Server name shown in MCP clients |
 
-| Setting | Default |
-|---------|---------|
-| `include` | `["**/*.md", "**/*.mdx"]` |
-| `exclude` | `["**/node_modules/**"]` |
-| `name` | `docs-mcp` |
+CLI args override config file values. Paths are resolved relative to the working directory.
 
 ## Tools
 
 ### `search_docs`
 
-Full-text search across all documentation pages.
+Full-text search across all documentation pages. Returns ranked results with text excerpts.
 
 - **query** (string, required) — The search query
-- **limit** (number, optional, default: 5) — Max results
+- **limit** (number, optional, default: 5) — Max results to return
 
 ### `get_page`
 
-Retrieve the full content of a specific page.
+Retrieve the full Markdown content of a specific page, including frontmatter metadata.
 
-- **path** (string, required) — Page path relative to docs root (e.g. `backend/payments`)
+- **path** (string, required) — Page path relative to docs root, without extension (e.g. `backend/payments`)
 
 ### `list_sections`
 
-List all documentation sections and their pages. No parameters.
-
-## How It Works
-
-1. On startup, the server checks if the search index needs rebuilding (compares file modification times)
-2. If stale or missing, it parses all Markdown/MDX files, strips MDX syntax, and builds a [Flexsearch](https://github.com/nextapps-de/flexsearch) index
-3. The index is stored in `.docs-mcp/` in your project root (add to `.gitignore`)
-4. Three MCP tools are exposed over stdio transport
+List all documentation sections and their pages. Returns a structured table of contents. No parameters.
 
 ## Add to .gitignore
 
+The search index is cached locally. Add this to your `.gitignore`:
+
 ```
 .docs-mcp/
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devista/docs-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Generic MCP server for full-text search over Markdown/MDX documentation",
   "type": "module",
   "bin": {