@devista/docs-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devista Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @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.
+
+## Quick Start
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
+    }
+  }
+}
+```
+
+That's it. The server will index your docs on first start and auto-rebuild when files change.
+
+## Configuration
+
+### CLI Args
+
+| Arg | Description |
+|-----|-------------|
+| `--docs <path>` | Path to documentation folder (required) |
+| `--name <name>` | Server name shown in MCP clients (default: `docs-mcp`) |
+
+### Config File
+
+Create `.docs-mcp.json` in your project root for persistent settings:
+
+```json
+{
+  "docs": "./src/content/docs",
+  "include": ["**/*.md", "**/*.mdx"],
+  "exclude": ["**/drafts/**"],
+  "name": "my-project-docs"
+}
+```
+
+CLI args override config file values. When using a config file, your `.mcp.json` simplifies to:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "npx",
+      "args": ["-y", "@devista/docs-mcp"]
+    }
+  }
+}
+```
+
+### Defaults
+
+| Setting | Default |
+|---------|---------|
+| `include` | `["**/*.md", "**/*.mdx"]` |
+| `exclude` | `["**/node_modules/**"]` |
+| `name` | `docs-mcp` |
+
+## Tools
+
+### `search_docs`
+
+Full-text search across all documentation pages.
+
+- **query** (string, required) — The search query
+- **limit** (number, optional, default: 5) — Max results
+
+### `get_page`
+
+Retrieve the full content of a specific page.
+
+- **path** (string, required) — Page path relative to docs root (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
+
+## Add to .gitignore
+
+```
+.docs-mcp/
+```
+
+## License
+
+MIT

package/bin/docs-mcp.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { promises as fs } from "fs";
+import { parseCliArgs, loadConfigFile, resolveConfig } from "../src/config.js";
+import { startServer } from "../src/server.js";
+
+async function main() {
+  const cwd = process.cwd();
+  const cliArgs = parseCliArgs(process.argv);
+  const fileConfig = await loadConfigFile(cwd);
+
+  let config;
+  try {
+    config = resolveConfig(cliArgs, fileConfig, cwd);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Validate docs path exists
+  try {
+    const stat = await fs.stat(config.docs);
+    if (!stat.isDirectory()) {
+      console.error(`Error: docs path '${config.docs}' is not a directory`);
+      process.exit(1);
+    }
+  } catch {
+    console.error(
+      `Error: docs path '${config.docs}' does not exist or is not a directory`
+    );
+    process.exit(1);
+  }
+
+  await startServer(config);
+}
+
+main().catch((err) => {
+  console.error("docs-mcp failed to start:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@devista/docs-mcp",
+  "version": "1.0.0",
+  "description": "Generic MCP server for full-text search over Markdown/MDX documentation",
+  "type": "module",
+  "bin": {
+    "docs-mcp": "./bin/docs-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devista-consulting/docs-mcp.git"
+  },
+  "keywords": ["mcp", "documentation", "search", "markdown", "ai", "claude"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-glob": "^3.3.0",
+    "flexsearch": "^0.8.0",
+    "gray-matter": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,47 @@
+import { promises as fs } from "fs";
+import path from "path";
+
+const DEFAULTS = {
+  include: ["**/*.md", "**/*.mdx"],
+  exclude: ["**/node_modules/**"],
+  name: "docs-mcp",
+};
+
+export function parseCliArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--docs" && argv[i + 1]) {
+      args.docs = argv[++i];
+    } else if (argv[i] === "--name" && argv[i + 1]) {
+      args.name = argv[++i];
+    }
+  }
+  return args;
+}
+
+export async function loadConfigFile(cwd) {
+  try {
+    const configPath = path.join(cwd, ".docs-mcp.json");
+    const raw = await fs.readFile(configPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function resolveConfig(cliArgs, fileConfig, cwd) {
+  const docs = cliArgs.docs || fileConfig.docs;
+  if (!docs) {
+    throw new Error(
+      "--docs path is required. Provide it via CLI arg or .docs-mcp.json"
+    );
+  }
+
+  return {
+    docs: path.resolve(cwd, docs),
+    include: cliArgs.include || fileConfig.include || DEFAULTS.include,
+    exclude: cliArgs.exclude || fileConfig.exclude || DEFAULTS.exclude,
+    name: cliArgs.name || fileConfig.name || DEFAULTS.name,
+    dataDir: path.join(cwd, ".docs-mcp"),
+  };
+}

package/src/freshness.js

@@ -0,0 +1,29 @@
+import { promises as fs } from "fs";
+import path from "path";
+import fg from "fast-glob";
+
+export async function isIndexStale(config) {
+  const indexPath = path.join(config.dataDir, "documents.json");
+
+  try {
+    const indexStat = await fs.stat(indexPath);
+    const indexMtime = indexStat.mtimeMs;
+
+    const files = await fg(config.include, {
+      cwd: config.docs,
+      ignore: config.exclude,
+      absolute: true,
+    });
+
+    for (const file of files) {
+      const stat = await fs.stat(file);
+      if (stat.mtimeMs > indexMtime) {
+        return true;
+      }
+    }
+
+    return false;
+  } catch {
+    return true;
+  }
+}

package/src/indexer.js

@@ -0,0 +1,121 @@
+import matter from "gray-matter";
+import { promises as fs } from "fs";
+import path from "path";
+import { Document } from "flexsearch";
+import fg from "fast-glob";
+
+export function parseDocFile(rawContent, relativePath) {
+  const { data: frontmatter, content } = matter(rawContent);
+
+  const body = stripMdxSyntax(content);
+  const section = relativePath.includes("/")
+    ? relativePath.split("/")[0]
+    : "";
+
+  return {
+    path: relativePath,
+    title: frontmatter.title || "",
+    description: frontmatter.description || "",
+    body: body.trim(),
+    section,
+  };
+}
+
+function stripMdxSyntax(content) {
+  return content
+    .replace(/^import\s+.*$/gm, "")
+    .replace(/<[A-Z][A-Za-z]*(?:\s[^>]*)?\/?>/g, "")
+    .replace(/<\/[A-Z][A-Za-z]*>/g, "")
+    .replace(/\n{3,}/g, "\n\n");
+}
+
+export async function collectDocFiles(docsDir, include, exclude) {
+  const files = await fg(include, {
+    cwd: docsDir,
+    ignore: exclude,
+    absolute: false,
+  });
+
+  const docs = [];
+  for (const file of files.sort()) {
+    const fullPath = path.join(docsDir, file);
+    try {
+      const rawContent = await fs.readFile(fullPath, "utf8");
+      const stat = await fs.stat(fullPath);
+      const pathWithoutExt = file.replace(/\.(mdx?|md)$/, "");
+      const doc = parseDocFile(rawContent, pathWithoutExt);
+      docs.push({ ...doc, lastModified: stat.mtime.toISOString() });
+    } catch (err) {
+      console.error(`Warning: skipping ${file}: ${err.message}`);
+    }
+  }
+
+  return docs;
+}
+
+export function createSearchIndex() {
+  return new Document({
+    tokenize: "forward",
+    document: {
+      id: "path",
+      index: [
+        { field: "title", resolution: 9 },
+        { field: "description", resolution: 7 },
+        { field: "body", resolution: 5 },
+      ],
+      store: ["title", "description", "section"],
+    },
+  });
+}
+
+export async function buildIndex(docs, outputDir) {
+  const index = createSearchIndex();
+
+  const documentStore = {};
+  for (const doc of docs) {
+    index.add(doc);
+    documentStore[doc.path] = {
+      title: doc.title,
+      description: doc.description,
+      body: doc.body,
+      section: doc.section,
+      lastModified: doc.lastModified,
+    };
+  }
+
+  await fs.mkdir(outputDir, { recursive: true });
+  await fs.writeFile(
+    path.join(outputDir, "documents.json"),
+    JSON.stringify(documentStore, null, 2),
+    "utf8"
+  );
+
+  const indexDir = path.join(outputDir, "search-index");
+  await fs.mkdir(indexDir, { recursive: true });
+  await index.export(async (key, data) => {
+    if (data !== undefined && data !== null) {
+      await fs.writeFile(
+        path.join(indexDir, key.toString()),
+        typeof data === "string" ? data : JSON.stringify(data),
+        "utf8"
+      );
+    }
+  });
+
+  return { documentCount: docs.length };
+}
+
+export async function loadIndex(dataDir) {
+  const documentsPath = path.join(dataDir, "documents.json");
+  const documents = JSON.parse(await fs.readFile(documentsPath, "utf8"));
+
+  const index = createSearchIndex();
+  const indexDir = path.join(dataDir, "search-index");
+  const files = await fs.readdir(indexDir);
+  for (const file of files) {
+    const data = await fs.readFile(path.join(indexDir, file), "utf8");
+    index.import(file, data);
+  }
+
+  return { index, documents };
+}

package/src/server.js

@@ -0,0 +1,89 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { isIndexStale } from "./freshness.js";
+import { collectDocFiles, buildIndex, loadIndex } from "./indexer.js";
+import { searchDocs } from "./tools/search-docs.js";
+import { getPage } from "./tools/get-page.js";
+import { listSections } from "./tools/list-sections.js";
+
+async function ensureIndex(config) {
+  const stale = await isIndexStale(config);
+
+  if (stale) {
+    console.error("Index is stale or missing, rebuilding...");
+    const docs = await collectDocFiles(config.docs, config.include, config.exclude);
+    await buildIndex(docs, config.dataDir);
+    console.error(`Rebuilt index: ${docs.length} documents`);
+  }
+
+  return loadIndex(config.dataDir);
+}
+
+export async function startServer(config) {
+  const { index, documents } = await ensureIndex(config);
+
+  const server = new McpServer({
+    name: config.name,
+    version: "1.0.0",
+  });
+
+  server.registerTool(
+    "search_docs",
+    {
+      description:
+        "Full-text search across documentation. Returns ranked results with excerpts.",
+      inputSchema: {
+        query: z.string().describe("The search query"),
+        limit: z
+          .number()
+          .optional()
+          .default(5)
+          .describe("Maximum number of results to return (default: 5)"),
+      },
+    },
+    async ({ query, limit }) => {
+      const results = searchDocs(index, documents, query, limit);
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+      };
+    }
+  );
+
+  server.registerTool(
+    "get_page",
+    {
+      description:
+        "Retrieve the full content of a specific documentation page by its path.",
+      inputSchema: {
+        path: z
+          .string()
+          .describe("Page path relative to docs root (e.g. 'backend/payments')"),
+      },
+    },
+    async ({ path: pagePath }) => {
+      const result = getPage(documents, pagePath);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  server.registerTool(
+    "list_sections",
+    {
+      description:
+        "List all documentation sections and their pages.",
+      inputSchema: {},
+    },
+    async () => {
+      const result = listSections(documents);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/tools/get-page.js

@@ -0,0 +1,19 @@
+export function getPage(documents, pagePath) {
+  const normalizedPath = pagePath.replace(/\/+$/, "");
+  const doc = documents[normalizedPath];
+
+  if (!doc) {
+    return {
+      error: `Page '${normalizedPath}' not found. Use list_sections to see available pages.`,
+    };
+  }
+
+  return {
+    path: normalizedPath,
+    title: doc.title,
+    description: doc.description,
+    body: doc.body,
+    section: doc.section,
+    lastModified: doc.lastModified,
+  };
+}

package/src/tools/list-sections.js

@@ -0,0 +1,23 @@
+export function listSections(documents) {
+  const sectionMap = new Map();
+
+  for (const [docPath, doc] of Object.entries(documents)) {
+    const section = doc.section || "";
+    if (!sectionMap.has(section)) {
+      sectionMap.set(section, []);
+    }
+    sectionMap.get(section).push({ path: docPath, title: doc.title });
+  }
+
+  for (const pages of sectionMap.values()) {
+    pages.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  const sortedSections = [...sectionMap.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, pages]) => ({ name, pages }));
+
+  const totalPages = Object.keys(documents).length;
+
+  return { sections: sortedSections, totalPages };
+}

package/src/tools/search-docs.js

@@ -0,0 +1,53 @@
+const EXCERPT_LENGTH = 200;
+
+export function generateExcerpt(body, query) {
+  const terms = query.toLowerCase().split(/\s+/);
+  const lowerBody = body.toLowerCase();
+
+  let firstIndex = -1;
+  for (const term of terms) {
+    const idx = lowerBody.indexOf(term);
+    if (idx !== -1 && (firstIndex === -1 || idx < firstIndex)) {
+      firstIndex = idx;
+    }
+  }
+
+  if (firstIndex === -1) {
+    return body.slice(0, EXCERPT_LENGTH).trim();
+  }
+
+  const start = Math.max(0, firstIndex - 80);
+  const end = Math.min(body.length, firstIndex + EXCERPT_LENGTH - 80);
+  const excerpt = body.slice(start, end).trim();
+
+  return (start > 0 ? "..." : "") + excerpt + (end < body.length ? "..." : "");
+}
+
+export function searchDocs(index, documents, query, limit) {
+  const rawResults = index.search(query, { limit, enrich: true });
+
+  const seen = new Set();
+  const results = [];
+
+  for (const fieldResult of rawResults) {
+    for (const item of fieldResult.result) {
+      const docPath = typeof item === "object" ? item.id : item;
+      if (seen.has(docPath)) continue;
+      seen.add(docPath);
+
+      const doc = documents[docPath];
+      if (!doc) continue;
+
+      results.push({
+        path: docPath,
+        title: doc.title,
+        excerpt: generateExcerpt(doc.body, query),
+      });
+
+      if (results.length >= limit) break;
+    }
+    if (results.length >= limit) break;
+  }
+
+  return results;
+}