mcp-server-markdown 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofer Shapira
+
+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,113 @@
+# mcp-server-markdown
+
+[![npm version](https://img.shields.io/npm/v/mcp-server-markdown.svg)](https://www.npmjs.com/package/mcp-server-markdown)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-server-markdown.svg)](https://www.npmjs.com/package/mcp-server-markdown)
+[![CI](https://github.com/ofershap/mcp-server-markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/ofershap/mcp-server-markdown/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Search, navigate, and extract content from local markdown files. Full-text search, section extraction, heading navigation, code block discovery, and frontmatter parsing.
+
+```bash
+npx mcp-server-markdown
+```
+
+> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Reads local `.md` files, no auth needed.
+
+![MCP server for searching and navigating markdown documentation](assets/demo.gif)
+
+<sub>Demo built with <a href="https://github.com/ofershap/remotion-readme-kit">remotion-readme-kit</a></sub>
+
+## Why
+
+Tools like Context7 are great for looking up library docs from npm, but they don't help with your own documentation. Project wikis, internal knowledge bases, architecture decision records, onboarding guides: they all live as markdown files in your repo or on disk. The filesystem MCP server can read those files, but it treats them as raw text. It doesn't understand headings, sections, or code blocks. This server does. Point it at a directory and your assistant can search across all your docs, pull out a specific section by heading, list the table of contents, or find every TypeScript code example in your knowledge base.
+
+## Tools
+
+| Tool               | What it does                                                               |
+| ------------------ | -------------------------------------------------------------------------- |
+| `list_files`       | List all .md files in a directory recursively (sorted alphabetically)      |
+| `search_docs`      | Full-text search across all .md files (case-insensitive, up to 50 results) |
+| `get_section`      | Extract a section by heading until the next heading of same/higher level   |
+| `list_headings`    | List all headings as a table of contents                                   |
+| `find_code_blocks` | Find fenced code blocks, optionally filter by language (e.g. typescript)   |
+| `get_frontmatter`  | Parse YAML frontmatter metadata at the start of a file                     |
+
+## Quick Start
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "markdown": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-markdown"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "markdown": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-markdown"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to user settings or `.vscode/mcp.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "markdown": {
+        "command": "npx",
+        "args": ["-y", "mcp-server-markdown"]
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+- "Search all docs in ./docs for mentions of 'authentication'"
+- "Show me the 'API Reference' section from README.md"
+- "List all headings in CONTRIBUTING.md"
+- "Find all TypeScript code blocks in the docs"
+- "What's the frontmatter metadata in this file?"
+- "Give me the table of contents for our architecture docs"
+
+## Development
+
+```bash
+git clone https://github.com/ofershap/mcp-server-markdown.git
+cd mcp-server-markdown
+npm install
+npm test
+npm run build
+```
+
+## Author
+
+**Ofer Shapira**
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-ofershap-blue?logo=linkedin)](https://linkedin.com/in/ofershap)
+[![GitHub](https://img.shields.io/badge/GitHub-ofershap-black?logo=github)](https://github.com/ofershap)
+
+## License
+
+MIT © 2026 Ofer Shapira

package/dist/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import path2 from "path";
+import { z } from "zod";
+
+// src/markdown.ts
+import fs from "fs/promises";
+import path from "path";
+async function walkDir(dir, baseDir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(baseDir, fullPath);
+    if (entry.isDirectory()) {
+      const subFiles = await walkDir(fullPath, baseDir);
+      files.push(...subFiles);
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(relativePath);
+    }
+  }
+  return files;
+}
+async function listMarkdownFiles(directory) {
+  const absDir = path.resolve(directory);
+  const stat = await fs.stat(absDir);
+  if (!stat.isDirectory()) {
+    throw new Error(`Not a directory: ${directory}`);
+  }
+  const files = await walkDir(absDir, absDir);
+  return files.sort();
+}
+async function searchDocs(directory, query) {
+  const absDir = path.resolve(directory);
+  const files = await listMarkdownFiles(absDir);
+  const results = [];
+  const lowerQuery = query.toLowerCase();
+  const limit = 50;
+  for (const file of files) {
+    if (results.length >= limit) break;
+    const fullPath = path.join(absDir, file);
+    const content = await fs.readFile(fullPath, "utf-8");
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length && results.length < limit; i++) {
+      const line = lines[i];
+      if (line !== void 0 && line.toLowerCase().includes(lowerQuery)) {
+        results.push({ file, line: i + 1, content: line });
+      }
+    }
+  }
+  return results;
+}
+async function getSection(filePath, heading) {
+  const absPath = path.resolve(filePath);
+  const content = await fs.readFile(absPath, "utf-8");
+  const lines = content.split("\n");
+  const lowerHeading = heading.toLowerCase().trim();
+  const headingRe = /^(#{1,6})\s+(.+)$/;
+  let targetLevel = 0;
+  let startLine = -1;
+  let endLine = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line !== void 0 ? line.match(headingRe) : null;
+    if (match && match[1] !== void 0 && match[2] !== void 0) {
+      const level = match[1].length;
+      const text = match[2].trim().toLowerCase();
+      if (text === lowerHeading) {
+        targetLevel = level;
+        startLine = i;
+        break;
+      }
+    }
+  }
+  if (startLine < 0) {
+    return "";
+  }
+  for (let i = startLine + 1; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line !== void 0 ? line.match(headingRe) : null;
+    if (match && match[1] !== void 0) {
+      const level = match[1].length;
+      if (level <= targetLevel) {
+        endLine = i;
+        break;
+      }
+    }
+  }
+  return lines.slice(startLine, endLine).join("\n").trim();
+}
+async function listHeadings(filePath) {
+  const absPath = path.resolve(filePath);
+  const content = await fs.readFile(absPath, "utf-8");
+  const lines = content.split("\n");
+  const headings = [];
+  const headingRe = /^(#{1,6})\s+(.+)$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line !== void 0 ? line.match(headingRe) : null;
+    if (match && match[1] !== void 0 && match[2] !== void 0) {
+      headings.push({
+        level: match[1].length,
+        text: match[2].trim(),
+        line: i + 1
+      });
+    }
+  }
+  return headings;
+}
+async function findCodeBlocks(filePath, language) {
+  const absPath = path.resolve(filePath);
+  const content = await fs.readFile(absPath, "utf-8");
+  const lines = content.split("\n");
+  const blocks = [];
+  const fenceRe = /^```(\w*)\s*$/;
+  let inBlock = false;
+  let blockLang = "";
+  let blockStart = 0;
+  const blockLines = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0) continue;
+    const fence = line.match(fenceRe);
+    if (fence) {
+      if (!inBlock) {
+        inBlock = true;
+        blockLang = fence[1] ?? "";
+        blockStart = i + 1;
+        blockLines.length = 0;
+      } else {
+        inBlock = false;
+        if (language === void 0 || blockLang.toLowerCase() === language.toLowerCase()) {
+          blocks.push({
+            language: blockLang,
+            code: blockLines.join("\n"),
+            line: blockStart
+          });
+        }
+      }
+    } else if (inBlock) {
+      blockLines.push(line);
+    }
+  }
+  return blocks;
+}
+async function getFrontmatter(filePath) {
+  const absPath = path.resolve(filePath);
+  const content = await fs.readFile(absPath, "utf-8");
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match || match[1] === void 0) return null;
+  const yaml = match[1];
+  const result = {};
+  const keyValueRe = /^([^:#\s]+):\s*(.*)$/m;
+  for (const line of yaml.split("\n")) {
+    const kv = line.trim().match(keyValueRe);
+    const key = kv?.[1];
+    const valRaw = kv?.[2];
+    if (key !== void 0 && valRaw !== void 0) {
+      const keyTrim = key.trim();
+      let val = valRaw.trim();
+      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
+        val = val.slice(1, -1);
+      }
+      result[keyTrim] = val;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+// src/index.ts
+var server = new McpServer({
+  name: "mcp-server-markdown",
+  version: "1.0.0"
+});
+server.tool(
+  "list_files",
+  "List all .md files in a directory recursively. Returns relative paths sorted alphabetically.",
+  {
+    directory: z.string().describe("Path to the directory to scan (e.g. ./docs)")
+  },
+  async ({ directory }) => {
+    const absDir = path2.resolve(directory);
+    const files = await listMarkdownFiles(absDir);
+    const text = files.length > 0 ? files.join("\n") : "(no markdown files found)";
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "search_docs",
+  "Full-text search across all .md files in a directory. Returns file, line number, and matching line. Limited to 50 results.",
+  {
+    directory: z.string().describe("Path to the directory to search (e.g. ./docs)"),
+    query: z.string().describe("Search string (case-insensitive)")
+  },
+  async ({ directory, query }) => {
+    const absDir = path2.resolve(directory);
+    const results = await searchDocs(absDir, query);
+    const lines = results.map((r) => `${r.file}:${r.line} ${r.content}`);
+    const text = lines.length > 0 ? lines.join("\n") : "(no matches)";
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "get_section",
+  "Extract a section by heading from a markdown file. Returns content from that heading until the next heading of same or higher level.",
+  {
+    file: z.string().describe("Path to the markdown file"),
+    heading: z.string().describe("Heading text to find (case-insensitive)")
+  },
+  async ({ file, heading }) => {
+    const absPath = path2.resolve(file);
+    const content = await getSection(absPath, heading);
+    const text = content || `(heading "${heading}" not found)`;
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "list_headings",
+  "List all headings (# through ######) in a markdown file as a table of contents.",
+  {
+    file: z.string().describe("Path to the markdown file")
+  },
+  async ({ file }) => {
+    const absPath = path2.resolve(file);
+    const headings = await listHeadings(absPath);
+    const lines = headings.map(
+      (h) => `${"  ".repeat(h.level - 1)}- ${h.text} (L${h.line})`
+    );
+    const text = lines.length > 0 ? lines.join("\n") : "(no headings found)";
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "find_code_blocks",
+  "Find all fenced code blocks in a markdown file. Optionally filter by language (e.g. typescript, python).",
+  {
+    file: z.string().describe("Path to the markdown file"),
+    language: z.string().optional().describe("Optional: filter by language (e.g. typescript, python)")
+  },
+  async ({ file, language }) => {
+    const absPath = path2.resolve(file);
+    const blocks = await findCodeBlocks(absPath, language);
+    const parts = blocks.map((b) => {
+      const lang = b.language || "(no lang)";
+      return `--- ${lang} (L${b.line}) ---
+${b.code}`;
+    });
+    const text = parts.length > 0 ? parts.join("\n\n") : "(no code blocks found)";
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "get_frontmatter",
+  "Parse YAML frontmatter (between --- delimiters) at the start of a markdown file. Returns key-value metadata.",
+  {
+    file: z.string().describe("Path to the markdown file")
+  },
+  async ({ file }) => {
+    const absPath = path2.resolve(file);
+    const frontmatter = await getFrontmatter(absPath);
+    if (!frontmatter) {
+      return {
+        content: [{ type: "text", text: "(no frontmatter)" }]
+      };
+    }
+    const lines = Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`);
+    return {
+      content: [{ type: "text", text: lines.join("\n") }]
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/markdown.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport path from \"node:path\";\nimport { z } from \"zod\";\nimport {\n  listMarkdownFiles,\n  searchDocs,\n  getSection,\n  listHeadings,\n  findCodeBlocks,\n  getFrontmatter,\n} from \"./markdown.js\";\n\nconst server = new McpServer({\n  name: \"mcp-server-markdown\",\n  version: \"1.0.0\",\n});\n\nserver.tool(\n  \"list_files\",\n  \"List all .md files in a directory recursively. Returns relative paths sorted alphabetically.\",\n  {\n    directory: z\n      .string()\n      .describe(\"Path to the directory to scan (e.g. ./docs)\"),\n  },\n  async ({ directory }) => {\n    const absDir = path.resolve(directory);\n    const files = await listMarkdownFiles(absDir);\n    const text =\n      files.length > 0 ? files.join(\"\\n\") : \"(no markdown files found)\";\n    return { content: [{ type: \"text\" as const, text }] };\n  },\n);\n\nserver.tool(\n  \"search_docs\",\n  \"Full-text search across all .md files in a directory. Returns file, line number, and matching line. Limited to 50 results.\",\n  {\n    directory: z\n      .string()\n      .describe(\"Path to the directory to search (e.g. ./docs)\"),\n    query: z.string().describe(\"Search string (case-insensitive)\"),\n  },\n  async ({ directory, query }) => {\n    const absDir = path.resolve(directory);\n    const results = await searchDocs(absDir, query);\n    const lines = results.map((r) => `${r.file}:${r.line} ${r.content}`);\n    const text = lines.length > 0 ? lines.join(\"\\n\") : \"(no matches)\";\n    return { content: [{ type: \"text\" as const, text }] };\n  },\n);\n\nserver.tool(\n  \"get_section\",\n  \"Extract a section by heading from a markdown file. Returns content from that heading until the next heading of same or higher level.\",\n  {\n    file: z.string().describe(\"Path to the markdown file\"),\n    heading: z.string().describe(\"Heading text to find (case-insensitive)\"),\n  },\n  async ({ file, heading }) => {\n    const absPath = path.resolve(file);\n    const content = await getSection(absPath, heading);\n    const text = content || `(heading \"${heading}\" not found)`;\n    return { content: [{ type: \"text\" as const, text }] };\n  },\n);\n\nserver.tool(\n  \"list_headings\",\n  \"List all headings (# through ######) in a markdown file as a table of contents.\",\n  {\n    file: z.string().describe(\"Path to the markdown file\"),\n  },\n  async ({ file }) => {\n    const absPath = path.resolve(file);\n    const headings = await listHeadings(absPath);\n    const lines = headings.map(\n      (h) => `${\"  \".repeat(h.level - 1)}- ${h.text} (L${h.line})`,\n    );\n    const text = lines.length > 0 ? lines.join(\"\\n\") : \"(no headings found)\";\n    return { content: [{ type: \"text\" as const, text }] };\n  },\n);\n\nserver.tool(\n  \"find_code_blocks\",\n  \"Find all fenced code blocks in a markdown file. Optionally filter by language (e.g. typescript, python).\",\n  {\n    file: z.string().describe(\"Path to the markdown file\"),\n    language: z\n      .string()\n      .optional()\n      .describe(\"Optional: filter by language (e.g. typescript, python)\"),\n  },\n  async ({ file, language }) => {\n    const absPath = path.resolve(file);\n    const blocks = await findCodeBlocks(absPath, language);\n    const parts = blocks.map((b) => {\n      const lang = b.language || \"(no lang)\";\n      return `--- ${lang} (L${b.line}) ---\\n${b.code}`;\n    });\n    const text =\n      parts.length > 0 ? parts.join(\"\\n\\n\") : \"(no code blocks found)\";\n    return { content: [{ type: \"text\" as const, text }] };\n  },\n);\n\nserver.tool(\n  \"get_frontmatter\",\n  \"Parse YAML frontmatter (between --- delimiters) at the start of a markdown file. Returns key-value metadata.\",\n  {\n    file: z.string().describe(\"Path to the markdown file\"),\n  },\n  async ({ file }) => {\n    const absPath = path.resolve(file);\n    const frontmatter = await getFrontmatter(absPath);\n    if (!frontmatter) {\n      return {\n        content: [{ type: \"text\" as const, text: \"(no frontmatter)\" }],\n      };\n    }\n    const lines = Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`);\n    return {\n      content: [{ type: \"text\" as const, text: lines.join(\"\\n\") }],\n    };\n  },\n);\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((error) => {\n  console.error(\"Fatal error:\", error);\n  process.exit(1);\n});\n","import fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nexport interface SearchResult {\n  file: string;\n  line: number;\n  content: string;\n}\n\nexport interface Heading {\n  level: number;\n  text: string;\n  line: number;\n}\n\nexport interface CodeBlock {\n  language: string;\n  code: string;\n  line: number;\n}\n\nexport type Frontmatter = Record<string, string>;\n\nasync function walkDir(dir: string, baseDir: string): Promise<string[]> {\n  const entries = await fs.readdir(dir, { withFileTypes: true });\n  const files: string[] = [];\n  for (const entry of entries) {\n    const fullPath = path.join(dir, entry.name);\n    const relativePath = path.relative(baseDir, fullPath);\n    if (entry.isDirectory()) {\n      const subFiles = await walkDir(fullPath, baseDir);\n      files.push(...subFiles);\n    } else if (entry.isFile() && entry.name.endsWith(\".md\")) {\n      files.push(relativePath);\n    }\n  }\n  return files;\n}\n\nexport async function listMarkdownFiles(directory: string): Promise<string[]> {\n  const absDir = path.resolve(directory);\n  const stat = await fs.stat(absDir);\n  if (!stat.isDirectory()) {\n    throw new Error(`Not a directory: ${directory}`);\n  }\n  const files = await walkDir(absDir, absDir);\n  return files.sort();\n}\n\nexport async function searchDocs(\n  directory: string,\n  query: string,\n): Promise<SearchResult[]> {\n  const absDir = path.resolve(directory);\n  const files = await listMarkdownFiles(absDir);\n  const results: SearchResult[] = [];\n  const lowerQuery = query.toLowerCase();\n  const limit = 50;\n\n  for (const file of files) {\n    if (results.length >= limit) break;\n    const fullPath = path.join(absDir, file);\n    const content = await fs.readFile(fullPath, \"utf-8\");\n    const lines = content.split(\"\\n\");\n    for (let i = 0; i < lines.length && results.length < limit; i++) {\n      const line = lines[i];\n      if (line !== undefined && line.toLowerCase().includes(lowerQuery)) {\n        results.push({ file, line: i + 1, content: line });\n      }\n    }\n  }\n  return results;\n}\n\nexport async function getSection(\n  filePath: string,\n  heading: string,\n): Promise<string> {\n  const absPath = path.resolve(filePath);\n  const content = await fs.readFile(absPath, \"utf-8\");\n  const lines = content.split(\"\\n\");\n  const lowerHeading = heading.toLowerCase().trim();\n  const headingRe = /^(#{1,6})\\s+(.+)$/;\n  let targetLevel = 0;\n  let startLine = -1;\n  let endLine = lines.length;\n\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i];\n    const match = line !== undefined ? line.match(headingRe) : null;\n    if (match && match[1] !== undefined && match[2] !== undefined) {\n      const level = match[1].length;\n      const text = match[2].trim().toLowerCase();\n      if (text === lowerHeading) {\n        targetLevel = level;\n        startLine = i;\n        break;\n      }\n    }\n  }\n\n  if (startLine < 0) {\n    return \"\";\n  }\n\n  for (let i = startLine + 1; i < lines.length; i++) {\n    const line = lines[i];\n    const match = line !== undefined ? line.match(headingRe) : null;\n    if (match && match[1] !== undefined) {\n      const level = match[1].length;\n      if (level <= targetLevel) {\n        endLine = i;\n        break;\n      }\n    }\n  }\n\n  return lines.slice(startLine, endLine).join(\"\\n\").trim();\n}\n\nexport async function listHeadings(filePath: string): Promise<Heading[]> {\n  const absPath = path.resolve(filePath);\n  const content = await fs.readFile(absPath, \"utf-8\");\n  const lines = content.split(\"\\n\");\n  const headings: Heading[] = [];\n  const headingRe = /^(#{1,6})\\s+(.+)$/;\n\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i];\n    const match = line !== undefined ? line.match(headingRe) : null;\n    if (match && match[1] !== undefined && match[2] !== undefined) {\n      headings.push({\n        level: match[1].length,\n        text: match[2].trim(),\n        line: i + 1,\n      });\n    }\n  }\n  return headings;\n}\n\nexport async function findCodeBlocks(\n  filePath: string,\n  language?: string,\n): Promise<CodeBlock[]> {\n  const absPath = path.resolve(filePath);\n  const content = await fs.readFile(absPath, \"utf-8\");\n  const lines = content.split(\"\\n\");\n  const blocks: CodeBlock[] = [];\n  const fenceRe = /^```(\\w*)\\s*$/;\n  let inBlock = false;\n  let blockLang = \"\";\n  let blockStart = 0;\n  const blockLines: string[] = [];\n\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i];\n    if (line === undefined) continue;\n    const fence = line.match(fenceRe);\n    if (fence) {\n      if (!inBlock) {\n        inBlock = true;\n        blockLang = fence[1] ?? \"\";\n        blockStart = i + 1;\n        blockLines.length = 0;\n      } else {\n        inBlock = false;\n        if (\n          language === undefined ||\n          blockLang.toLowerCase() === language.toLowerCase()\n        ) {\n          blocks.push({\n            language: blockLang,\n            code: blockLines.join(\"\\n\"),\n            line: blockStart,\n          });\n        }\n      }\n    } else if (inBlock) {\n      blockLines.push(line);\n    }\n  }\n  return blocks;\n}\n\nexport async function getFrontmatter(\n  filePath: string,\n): Promise<Frontmatter | null> {\n  const absPath = path.resolve(filePath);\n  const content = await fs.readFile(absPath, \"utf-8\");\n  const match = content.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---/);\n  if (!match || match[1] === undefined) return null;\n  const yaml = match[1];\n  const result: Frontmatter = {};\n  const keyValueRe = /^([^:#\\s]+):\\s*(.*)$/m;\n  for (const line of yaml.split(\"\\n\")) {\n    const kv = line.trim().match(keyValueRe);\n    const key = kv?.[1];\n    const valRaw = kv?.[2];\n    if (key !== undefined && valRaw !== undefined) {\n      const keyTrim = key.trim();\n      let val = valRaw.trim();\n      if (\n        (val.startsWith('\"') && val.endsWith('\"')) ||\n        (val.startsWith(\"'\") && val.endsWith(\"'\"))\n      ) {\n        val = val.slice(1, -1);\n      }\n      result[keyTrim] = val;\n    }\n  }\n  return Object.keys(result).length > 0 ? result : null;\n}\n"],"mappings":";;;AAAA,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AACrC,OAAOA,WAAU;AACjB,SAAS,SAAS;;;ACHlB,OAAO,QAAQ;AACf,OAAO,UAAU;AAsBjB,eAAe,QAAQ,KAAa,SAAoC;AACtE,QAAM,UAAU,MAAM,GAAG,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;AAC7D,QAAM,QAAkB,CAAC;AACzB,aAAW,SAAS,SAAS;AAC3B,UAAM,WAAW,KAAK,KAAK,KAAK,MAAM,IAAI;AAC1C,UAAM,eAAe,KAAK,SAAS,SAAS,QAAQ;AACpD,QAAI,MAAM,YAAY,GAAG;AACvB,YAAM,WAAW,MAAM,QAAQ,UAAU,OAAO;AAChD,YAAM,KAAK,GAAG,QAAQ;AAAA,IACxB,WAAW,MAAM,OAAO,KAAK,MAAM,KAAK,SAAS,KAAK,GAAG;AACvD,YAAM,KAAK,YAAY;AAAA,IACzB;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,kBAAkB,WAAsC;AAC5E,QAAM,SAAS,KAAK,QAAQ,SAAS;AACrC,QAAM,OAAO,MAAM,GAAG,KAAK,MAAM;AACjC,MAAI,CAAC,KAAK,YAAY,GAAG;AACvB,UAAM,IAAI,MAAM,oBAAoB,SAAS,EAAE;AAAA,EACjD;AACA,QAAM,QAAQ,MAAM,QAAQ,QAAQ,MAAM;AAC1C,SAAO,MAAM,KAAK;AACpB;AAEA,eAAsB,WACpB,WACA,OACyB;AACzB,QAAM,SAAS,KAAK,QAAQ,SAAS;AACrC,QAAM,QAAQ,MAAM,kBAAkB,MAAM;AAC5C,QAAM,UAA0B,CAAC;AACjC,QAAM,aAAa,MAAM,YAAY;AACrC,QAAM,QAAQ;AAEd,aAAW,QAAQ,OAAO;AACxB,QAAI,QAAQ,UAAU,MAAO;AAC7B,UAAM,WAAW,KAAK,KAAK,QAAQ,IAAI;AACvC,UAAM,UAAU,MAAM,GAAG,SAAS,UAAU,OAAO;AACnD,UAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,aAAS,IAAI,GAAG,IAAI,MAAM,UAAU,QAAQ,SAAS,OAAO,KAAK;AAC/D,YAAM,OAAO,MAAM,CAAC;AACpB,UAAI,SAAS,UAAa,KAAK,YAAY,EAAE,SAAS,UAAU,GAAG;AACjE,gBAAQ,KAAK,EAAE,MAAM,MAAM,IAAI,GAAG,SAAS,KAAK,CAAC;AAAA,MACnD;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,WACpB,UACA,SACiB;AACjB,QAAM,UAAU,KAAK,QAAQ,QAAQ;AACrC,QAAM,UAAU,MAAM,GAAG,SAAS,SAAS,OAAO;AAClD,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,eAAe,QAAQ,YAAY,EAAE,KAAK;AAChD,QAAM,YAAY;AAClB,MAAI,cAAc;AAClB,MAAI,YAAY;AAChB,MAAI,UAAU,MAAM;AAEpB,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,QAAQ,SAAS,SAAY,KAAK,MAAM,SAAS,IAAI;AAC3D,QAAI,SAAS,MAAM,CAAC,MAAM,UAAa,MAAM,CAAC,MAAM,QAAW;AAC7D,YAAM,QAAQ,MAAM,CAAC,EAAE;AACvB,YAAM,OAAO,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY;AACzC,UAAI,SAAS,cAAc;AACzB,sBAAc;AACd,oBAAY;AACZ;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,YAAY,GAAG;AACjB,WAAO;AAAA,EACT;AAEA,WAAS,IAAI,YAAY,GAAG,IAAI,MAAM,QAAQ,KAAK;AACjD,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,QAAQ,SAAS,SAAY,KAAK,MAAM,SAAS,IAAI;AAC3D,QAAI,SAAS,MAAM,CAAC,MAAM,QAAW;AACnC,YAAM,QAAQ,MAAM,CAAC,EAAE;AACvB,UAAI,SAAS,aAAa;AACxB,kBAAU;AACV;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,MAAM,WAAW,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK;AACzD;AAEA,eAAsB,aAAa,UAAsC;AACvE,QAAM,UAAU,KAAK,QAAQ,QAAQ;AACrC,QAAM,UAAU,MAAM,GAAG,SAAS,SAAS,OAAO;AAClD,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,WAAsB,CAAC;AAC7B,QAAM,YAAY;AAElB,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,QAAQ,SAAS,SAAY,KAAK,MAAM,SAAS,IAAI;AAC3D,QAAI,SAAS,MAAM,CAAC,MAAM,UAAa,MAAM,CAAC,MAAM,QAAW;AAC7D,eAAS,KAAK;AAAA,QACZ,OAAO,MAAM,CAAC,EAAE;AAAA,QAChB,MAAM,MAAM,CAAC,EAAE,KAAK;AAAA,QACpB,MAAM,IAAI;AAAA,MACZ,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,eACpB,UACA,UACsB;AACtB,QAAM,UAAU,KAAK,QAAQ,QAAQ;AACrC,QAAM,UAAU,MAAM,GAAG,SAAS,SAAS,OAAO;AAClD,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,SAAsB,CAAC;AAC7B,QAAM,UAAU;AAChB,MAAI,UAAU;AACd,MAAI,YAAY;AAChB,MAAI,aAAa;AACjB,QAAM,aAAuB,CAAC;AAE9B,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,OAAO,MAAM,CAAC;AACpB,QAAI,SAAS,OAAW;AACxB,UAAM,QAAQ,KAAK,MAAM,OAAO;AAChC,QAAI,OAAO;AACT,UAAI,CAAC,SAAS;AACZ,kBAAU;AACV,oBAAY,MAAM,CAAC,KAAK;AACxB,qBAAa,IAAI;AACjB,mBAAW,SAAS;AAAA,MACtB,OAAO;AACL,kBAAU;AACV,YACE,aAAa,UACb,UAAU,YAAY,MAAM,SAAS,YAAY,GACjD;AACA,iBAAO,KAAK;AAAA,YACV,UAAU;AAAA,YACV,MAAM,WAAW,KAAK,IAAI;AAAA,YAC1B,MAAM;AAAA,UACR,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF,WAAW,SAAS;AAClB,iBAAW,KAAK,IAAI;AAAA,IACtB;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,eACpB,UAC6B;AAC7B,QAAM,UAAU,KAAK,QAAQ,QAAQ;AACrC,QAAM,UAAU,MAAM,GAAG,SAAS,SAAS,OAAO;AAClD,QAAM,QAAQ,QAAQ,MAAM,6BAA6B;AACzD,MAAI,CAAC,SAAS,MAAM,CAAC,MAAM,OAAW,QAAO;AAC7C,QAAM,OAAO,MAAM,CAAC;AACpB,QAAM,SAAsB,CAAC;AAC7B,QAAM,aAAa;AACnB,aAAW,QAAQ,KAAK,MAAM,IAAI,GAAG;AACnC,UAAM,KAAK,KAAK,KAAK,EAAE,MAAM,UAAU;AACvC,UAAM,MAAM,KAAK,CAAC;AAClB,UAAM,SAAS,KAAK,CAAC;AACrB,QAAI,QAAQ,UAAa,WAAW,QAAW;AAC7C,YAAM,UAAU,IAAI,KAAK;AACzB,UAAI,MAAM,OAAO,KAAK;AACtB,UACG,IAAI,WAAW,GAAG,KAAK,IAAI,SAAS,GAAG,KACvC,IAAI,WAAW,GAAG,KAAK,IAAI,SAAS,GAAG,GACxC;AACA,cAAM,IAAI,MAAM,GAAG,EAAE;AAAA,MACvB;AACA,aAAO,OAAO,IAAI;AAAA,IACpB;AAAA,EACF;AACA,SAAO,OAAO,KAAK,MAAM,EAAE,SAAS,IAAI,SAAS;AACnD;;;ADvMA,IAAM,SAAS,IAAI,UAAU;AAAA,EAC3B,MAAM;AAAA,EACN,SAAS;AACX,CAAC;AAED,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,WAAW,EACR,OAAO,EACP,SAAS,6CAA6C;AAAA,EAC3D;AAAA,EACA,OAAO,EAAE,UAAU,MAAM;AACvB,UAAM,SAASC,MAAK,QAAQ,SAAS;AACrC,UAAM,QAAQ,MAAM,kBAAkB,MAAM;AAC5C,UAAM,OACJ,MAAM,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI;AACxC,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,WAAW,EACR,OAAO,EACP,SAAS,+CAA+C;AAAA,IAC3D,OAAO,EAAE,OAAO,EAAE,SAAS,kCAAkC;AAAA,EAC/D;AAAA,EACA,OAAO,EAAE,WAAW,MAAM,MAAM;AAC9B,UAAM,SAASA,MAAK,QAAQ,SAAS;AACrC,UAAM,UAAU,MAAM,WAAW,QAAQ,KAAK;AAC9C,UAAM,QAAQ,QAAQ,IAAI,CAAC,MAAM,GAAG,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE,OAAO,EAAE;AACnE,UAAM,OAAO,MAAM,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI;AACnD,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,MAAM,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,IACrD,SAAS,EAAE,OAAO,EAAE,SAAS,yCAAyC;AAAA,EACxE;AAAA,EACA,OAAO,EAAE,MAAM,QAAQ,MAAM;AAC3B,UAAM,UAAUA,MAAK,QAAQ,IAAI;AACjC,UAAM,UAAU,MAAM,WAAW,SAAS,OAAO;AACjD,UAAM,OAAO,WAAW,aAAa,OAAO;AAC5C,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,MAAM,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EACvD;AAAA,EACA,OAAO,EAAE,KAAK,MAAM;AAClB,UAAM,UAAUA,MAAK,QAAQ,IAAI;AACjC,UAAM,WAAW,MAAM,aAAa,OAAO;AAC3C,UAAM,QAAQ,SAAS;AAAA,MACrB,CAAC,MAAM,GAAG,KAAK,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,EAAE,IAAI,MAAM,EAAE,IAAI;AAAA,IAC3D;AACA,UAAM,OAAO,MAAM,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI;AACnD,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,MAAM,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,IACrD,UAAU,EACP,OAAO,EACP,SAAS,EACT,SAAS,wDAAwD;AAAA,EACtE;AAAA,EACA,OAAO,EAAE,MAAM,SAAS,MAAM;AAC5B,UAAM,UAAUA,MAAK,QAAQ,IAAI;AACjC,UAAM,SAAS,MAAM,eAAe,SAAS,QAAQ;AACrD,UAAM,QAAQ,OAAO,IAAI,CAAC,MAAM;AAC9B,YAAM,OAAO,EAAE,YAAY;AAC3B,aAAO,OAAO,IAAI,MAAM,EAAE,IAAI;AAAA,EAAU,EAAE,IAAI;AAAA,IAChD,CAAC;AACD,UAAM,OACJ,MAAM,SAAS,IAAI,MAAM,KAAK,MAAM,IAAI;AAC1C,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,IACE,MAAM,EAAE,OAAO,EAAE,SAAS,2BAA2B;AAAA,EACvD;AAAA,EACA,OAAO,EAAE,KAAK,MAAM;AAClB,UAAM,UAAUA,MAAK,QAAQ,IAAI;AACjC,UAAM,cAAc,MAAM,eAAe,OAAO;AAChD,QAAI,CAAC,aAAa;AAChB,aAAO;AAAA,QACL,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,mBAAmB,CAAC;AAAA,MAC/D;AAAA,IACF;AACA,UAAM,QAAQ,OAAO,QAAQ,WAAW,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE;AACtE,WAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,MAAM,KAAK,IAAI,EAAE,CAAC;AAAA,IAC7D;AAAA,EACF;AACF;AAEA,eAAe,OAAO;AACpB,QAAM,YAAY,IAAI,qBAAqB;AAC3C,QAAM,OAAO,QAAQ,SAAS;AAChC;AAEA,KAAK,EAAE,MAAM,CAAC,UAAU;AACtB,UAAQ,MAAM,gBAAgB,KAAK;AACnC,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":["path","path"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "mcp-server-markdown",
+  "version": "1.0.0",
+  "description": "MCP server for markdown files — search, extract sections, list headings, find code blocks across your docs directory",
+  "type": "module",
+  "bin": {
+    "mcp-server-markdown": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "markdown",
+    "documentation",
+    "docs",
+    "knowledge-base",
+    "search",
+    "headings",
+    "code-blocks",
+    "ai",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "author": "Ofer Shapira",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ofershap/mcp-server-markdown.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ofershap/mcp-server-markdown/issues"
+  },
+  "homepage": "https://github.com/ofershap/mcp-server-markdown#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js}": "eslint --fix",
+    "*.{json,md,yml,yaml}": "prettier --write"
+  }
+}