devdocs-mcp 1.0.0

package/README.md

@@ -0,0 +1,229 @@
+# DevDocs MCP Server
+
+A Model Context Protocol (MCP) server that provides API documentation from [DevDocs.io](https://devdocs.io) to AI assistants.
+
+**Runtime Requirement:** This server requires **Bun >= 1.0.0**.
+
+## Features
+
+- **List Documentation** - Browse all available documentation libraries
+- **Fuzzy Search** - Typo-tolerant search with relevance scoring powered by [Fuse.js](https://fusejs.io/)
+- **Get Documentation Pages** - Retrieve full documentation content in Markdown format
+- **File-based Caching** - Reduces API calls with configurable TTL
+- **Version Support** - Access specific library versions (e.g., `react~18`, `python~3.12`)
+
+## Installation
+
+```bash
+bun install
+```
+
+**This server only supports Bun runtime.**
+
+## Usage
+
+### Start the MCP Server
+
+```bash
+DEBUG=mcp:* bun start
+```
+
+### Configure in Claude Desktop
+
+After installing from npm, use `bunx`:
+
+```json
+{
+  "mcpServers": {
+    "devdocs": {
+      "command": "bunx",
+      "args": ["devdocs-mcp"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "devdocs": {
+      "command": "bun",
+      "args": ["run", "/path/to/devdocs-mcp/src/index.ts"]
+    }
+  }
+}
+```
+
+### Configure in Cursor
+
+After installing from npm, use `bunx`:
+
+```json
+{
+  "mcpServers": {
+    "devdocs": {
+      "command": "bunx",
+      "args": ["devdocs-mcp"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "devdocs": {
+      "command": "bun",
+      "args": ["run", "/path/to/devdocs-mcp/src/index.ts"]
+    }
+  }
+}
+```
+
+## MCP Tools
+
+### `list_available_docs`
+
+List all available documentation libraries from DevDocs.
+
+**Parameters:**
+
+- `filter` (optional): Filter libraries by name (e.g., "react", "python")
+
+**Example:**
+
+```
+List all React documentation
+→ list_available_docs({ filter: "react" })
+```
+
+### `search_docs`
+
+Search within a library's documentation with fuzzy matching support.
+
+**Parameters:**
+
+- `library` (required): Library slug (e.g., "react", "typescript", "python~3.12")
+- `query` (required): Search query
+- `limit` (optional): Maximum results (default: 10)
+- `fuzzy` (optional): Enable fuzzy search for typo-tolerant matching (default: true)
+- `threshold` (optional): Fuzzy search threshold from 0.0 (exact) to 1.0 (match anything) (default: 0.4)
+
+**Examples:**
+
+```
+# Basic search (fuzzy enabled by default)
+→ search_docs({ library: "react", query: "useState" })
+
+# Search with typos - still finds "useState"
+→ search_docs({ library: "react", query: "useStat" })
+
+# Exact match only (disable fuzzy)
+→ search_docs({ library: "react", query: "useState", fuzzy: false })
+
+# Stricter fuzzy matching
+→ search_docs({ library: "react", query: "useState", threshold: 0.2 })
+```
+
+### `get_doc_page`
+
+Get the content of a specific documentation page.
+
+**Parameters:**
+
+- `library` (required): Library slug
+- `path` (required): Documentation path
+
+**Example:**
+
+```
+Get React useState documentation
+→ get_doc_page({ library: "react", path: "reference/react/usestate" })
+```
+
+## Development
+
+### Run Tests
+
+```bash
+bun test
+```
+
+### Run Linter
+
+```bash
+bun lint
+```
+
+### CLI Test Script
+
+A CLI script is provided for manual testing:
+
+```bash
+# List available docs (optionally filtered)
+node scripts/test-cli.ts list react
+
+# Search within a library
+node scripts/test-cli.ts search react useState
+
+# Get a specific doc page
+node scripts/test-cli.ts get react reference/react/usestate
+```
+
+### Project Structure
+
+```
+devdocs-mcp/
+├── src/
+│   ├── index.ts              # Entry point (stdio transport)
+│   ├── server.ts             # MCP Server configuration
+│   ├── services/
+│   │   ├── file-cache.ts     # File-based cache with TTL
+│   │   └── devdocs-client.ts # DevDocs API client
+│   ├── tools/
+│   │   └── index.ts          # MCP tool implementations
+│   ├── utils/
+│   │   └── html-to-markdown.ts
+│   └── types/
+│       └── devdocs.ts
+├── test/                     # Test files (140 tests)
+├── scripts/
+│   └── test-cli.ts           # CLI test script
+├── cache/                    # Cache directory (gitignored)
+└── package.json
+```
+
+## Technical Details
+
+### Dependencies
+
+| Package                     | Version | Purpose                     |
+| --------------------------- | ------- | --------------------------- |
+| `@modelcontextprotocol/sdk` | ^1.25.3 | MCP protocol implementation |
+| `zod`                       | ^3.25.0 | Schema validation           |
+| `turndown`                  | ^7.2.2  | HTML to Markdown conversion |
+| `fuse.js`                   | ^7.1.0  | Fuzzy search                |
+
+### Cache TTL Settings
+
+| Data Type           | TTL      |
+| ------------------- | -------- |
+| Documentation list  | 24 hours |
+| Documentation index | 12 hours |
+| Documentation pages | 7 days   |
+
+### DevDocs API Endpoints
+
+| Endpoint                                          | Purpose            |
+| ------------------------------------------------- | ------------------ |
+| `https://devdocs.io/docs.json`                    | All available docs |
+| `https://devdocs.io/docs/{slug}/index.json`       | Doc index          |
+| `https://documents.devdocs.io/{slug}/{path}.html` | Doc content        |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "devdocs-mcp",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "MCP Server for fetching documentation from DevDocs",
+  "main": "src/index.ts",
+  "bin": {
+    "devdocs-mcp": "./src/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": ["src", "package.json", "README.md", "LICENSE"],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "test": "bun test",
+    "lint": "bunx @biomejs/biome check .",
+    "lint:fix": "bunx @biomejs/biome check --write .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "check": "bunx @biomejs/biome check --write . && bunx @biomejs/biome format --write .",
+    "check:ci": "bunx @biomejs/biome check . && bunx @biomejs/biome format .",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "fuse.js": "^7.1.0",
+    "turndown": "^7.2.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "^1.1.15",
+    "@types/turndown": "^5.0.6",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { createServer } from "./server.ts"
+
+async function main() {
+  const server = createServer()
+  const transport = new StdioServerTransport()
+
+  await server.connect(transport)
+
+  // Log to stderr (stdout is used for MCP protocol)
+  console.error("DevDocs MCP Server started")
+}
+
+main().catch(error => {
+  console.error("Fatal error:", error)
+  process.exit(1)
+})

package/src/server.ts

@@ -0,0 +1,96 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { z } from "zod"
+import { DEFAULT_CACHE_DIR, FileCache } from "./services/file-cache.ts"
+import { createTools } from "./tools/index.ts"
+
+export interface ServerOptions {
+  cacheDir?: string
+}
+
+export function createServer(options?: ServerOptions): McpServer {
+  const cacheDir = options?.cacheDir ?? DEFAULT_CACHE_DIR
+  const cache = new FileCache({ cacheDir, defaultTtl: 24 * 60 * 60 * 1000 })
+  const tools = createTools(cache)
+
+  const server = new McpServer({
+    name: "devdocs-mcp",
+    version: "1.0.0",
+  })
+
+  // Register tool: list_available_docs
+  server.registerTool(
+    "list_available_docs",
+    {
+      description:
+        "List all available documentation libraries from DevDocs. Use filter to search for specific libraries.",
+      inputSchema: {
+        filter: z.string().optional().describe("Filter libraries by name (e.g., 'react', 'python', 'typescript')"),
+      },
+    },
+    async ({ filter }) => {
+      try {
+        const result = await tools.listAvailableDocs({ filter })
+        return { content: [{ type: "text", text: result }] }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error"
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true }
+      }
+    },
+  )
+
+  // Register tool: search_docs
+  server.registerTool(
+    "search_docs",
+    {
+      description:
+        "Search within a library's documentation. Returns matching entries with their paths. Supports fuzzy search for typo-tolerant matching.",
+      inputSchema: {
+        library: z.string().describe("Library slug (e.g., 'react', 'typescript', 'python~3.12')"),
+        query: z.string().describe("Search query (e.g., 'useState', 'async function')"),
+        limit: z.number().optional().default(10).describe("Maximum results to return (default: 10)"),
+        fuzzy: z
+          .boolean()
+          .optional()
+          .default(true)
+          .describe("Enable fuzzy search for typo-tolerant matching (default: true)"),
+        threshold: z
+          .number()
+          .optional()
+          .default(0.4)
+          .describe("Fuzzy search threshold: 0.0 = exact match, 1.0 = match anything (default: 0.4)"),
+      },
+    },
+    async ({ library, query, limit, fuzzy, threshold }) => {
+      try {
+        const result = await tools.searchDocs({ library, query, limit, fuzzy, threshold })
+        return { content: [{ type: "text", text: result }] }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error"
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true }
+      }
+    },
+  )
+
+  // Register tool: get_doc_page
+  server.registerTool(
+    "get_doc_page",
+    {
+      description: "Get the content of a specific documentation page. Returns the documentation in Markdown format.",
+      inputSchema: {
+        library: z.string().describe("Library slug (e.g., 'react', 'typescript')"),
+        path: z.string().describe("Documentation path (e.g., 'reference/react/usestate')"),
+      },
+    },
+    async ({ library, path }) => {
+      try {
+        const result = await tools.getDocPage({ library, path })
+        return { content: [{ type: "text", text: result }] }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error"
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true }
+      }
+    },
+  )
+
+  return server
+}

package/src/services/devdocs-client.ts

@@ -0,0 +1,181 @@
+import Fuse from "fuse.js"
+import type { DevDocsDoc, DocEntry, DocIndex, ParsedSlug } from "../types/devdocs.ts"
+import { htmlToMarkdown } from "../utils/html-to-markdown.ts"
+import type { FileCache } from "./file-cache.ts"
+
+export interface SearchOptions {
+  /** Enable fuzzy search (default: true) */
+  fuzzy?: boolean
+  /** Fuzzy search threshold (0.0 = exact match, 1.0 = match anything, default: 0.4) */
+  threshold?: number
+}
+
+export interface SearchResult extends DocEntry {
+  /** Fuzzy search score (0 = perfect match, 1 = no match). Only present when fuzzy search is enabled. */
+  score?: number
+}
+
+export interface DevDocsClientOptions {
+  cache: FileCache
+  baseUrl?: string
+  documentsUrl?: string
+}
+
+const CACHE_KEYS = {
+  DOCS_LIST: "devdocs:docs-list",
+  DOC_INDEX: (slug: string) => `devdocs:index:${slug}`,
+  DOC_PAGE: (slug: string, path: string) => `devdocs:page:${slug}:${path}`,
+}
+
+const CACHE_TTL = {
+  DOCS_LIST: 24 * 60 * 60 * 1000, // 24 hours
+  DOC_INDEX: 12 * 60 * 60 * 1000, // 12 hours
+  DOC_PAGE: 7 * 24 * 60 * 60 * 1000, // 7 days
+}
+
+export class DevDocsClient {
+  private cache: FileCache
+  private baseUrl: string
+  private documentsUrl: string
+
+  constructor(options: DevDocsClientOptions) {
+    this.cache = options.cache
+    this.baseUrl = options.baseUrl ?? "https://devdocs.io"
+    this.documentsUrl = options.documentsUrl ?? "https://documents.devdocs.io"
+  }
+
+  /**
+   * Fetch all available documentation libraries
+   */
+  async listDocs(filter?: string): Promise<DevDocsDoc[]> {
+    const cacheKey = CACHE_KEYS.DOCS_LIST
+
+    // Try cache first
+    let docs = await this.cache.get<DevDocsDoc[]>(cacheKey)
+
+    if (!docs) {
+      const response = await fetch(`${this.baseUrl}/docs.json`)
+      if (!response.ok) {
+        throw new Error(`Failed to fetch docs list: ${response.status}`)
+      }
+      docs = (await response.json()) as DevDocsDoc[]
+      await this.cache.set(cacheKey, docs, { ttl: CACHE_TTL.DOCS_LIST })
+    }
+
+    // Apply filter if provided
+    if (filter) {
+      const lowerFilter = filter.toLowerCase()
+      docs = docs.filter(
+        doc => doc.name.toLowerCase().includes(lowerFilter) || doc.slug.toLowerCase().includes(lowerFilter),
+      )
+    }
+
+    return docs
+  }
+
+  /**
+   * Get documentation index for a specific library
+   */
+  async getDocIndex(slug: string): Promise<DocIndex> {
+    const cacheKey = CACHE_KEYS.DOC_INDEX(slug)
+
+    // Try cache first
+    let index = await this.cache.get<DocIndex>(cacheKey)
+
+    if (!index) {
+      const response = await fetch(`${this.baseUrl}/docs/${slug}/index.json`)
+      if (!response.ok) {
+        throw new Error(`Failed to fetch doc index for '${slug}': ${response.status}`)
+      }
+      index = (await response.json()) as DocIndex
+      await this.cache.set(cacheKey, index, { ttl: CACHE_TTL.DOC_INDEX })
+    }
+
+    return index
+  }
+
+  /**
+   * Search within a library's documentation
+   * Supports both exact substring matching and fuzzy search
+   */
+  async searchDocs(slug: string, query: string, limit = 10, options: SearchOptions = {}): Promise<SearchResult[]> {
+    const index = await this.getDocIndex(slug)
+    const { fuzzy = true, threshold = 0.4 } = options
+
+    // Handle empty query - return first N entries
+    if (!query || query.trim() === "") {
+      return index.entries.slice(0, limit).map(entry => ({ ...entry }))
+    }
+
+    if (fuzzy) {
+      // Use Fuse.js for fuzzy search
+      const fuse = new Fuse(index.entries, {
+        keys: [
+          { name: "name", weight: 0.7 },
+          { name: "path", weight: 0.2 },
+          { name: "type", weight: 0.1 },
+        ],
+        threshold,
+        includeScore: true,
+        ignoreLocation: true,
+        minMatchCharLength: 1,
+      })
+
+      const fuseResults = fuse.search(query, { limit })
+      return fuseResults.map(result => ({
+        ...result.item,
+        score: result.score,
+      }))
+    }
+    // Fallback to exact substring matching
+    const lowerQuery = query.toLowerCase()
+    const results = index.entries.filter(entry => {
+      return entry.name.toLowerCase().includes(lowerQuery) || entry.path.toLowerCase().includes(lowerQuery)
+    })
+    return results.slice(0, limit)
+  }
+
+  /**
+   * Get a specific documentation page content (as Markdown)
+   */
+  async getDocPage(slug: string, path: string): Promise<string> {
+    // Strip anchor from path (e.g., "fs#fspromisesreadfilepath-options" -> "fs")
+    // DevDocs paths may contain anchors that should not be part of the URL
+    const basePath = path.split("#")[0]
+    const cacheKey = CACHE_KEYS.DOC_PAGE(slug, basePath)
+
+    // Try cache first
+    let markdown = await this.cache.get<string>(cacheKey)
+
+    if (!markdown) {
+      const url = `${this.documentsUrl}/${slug}/${basePath}.html`
+      const response = await fetch(url)
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch doc page '${basePath}' for '${slug}': ${response.status}`)
+      }
+
+      const html = await response.text()
+      markdown = htmlToMarkdown(html)
+      await this.cache.set(cacheKey, markdown, { ttl: CACHE_TTL.DOC_PAGE })
+    }
+
+    return markdown
+  }
+
+  /**
+   * Parse a library slug to extract name and version
+   * Examples:
+   *   "react" -> { name: "react", version: undefined, slug: "react" }
+   *   "react~18" -> { name: "react", version: "18", slug: "react~18" }
+   *   "python~3.12" -> { name: "python", version: "3.12", slug: "python~3.12" }
+   */
+  parseSlug(slug: string): ParsedSlug {
+    const parts = slug.split("~")
+    return {
+      name: parts[0],
+      version: parts.length > 1 ? parts.slice(1).join("~") : undefined,
+      slug,
+    }
+  }
+}

package/src/services/file-cache.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+export interface CacheOptions {
+  cacheDir: string
+  defaultTtl: number // milliseconds
+}
+
+export interface SetOptions {
+  ttl?: number
+}
+
+interface CacheEntry<T> {
+  data: T
+  expiresAt: number
+}
+
+export const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".mcp", "devdocs")
+
+const DEFAULT_OPTIONS: CacheOptions = {
+  cacheDir: DEFAULT_CACHE_DIR,
+  defaultTtl: 24 * 60 * 60 * 1000, // 24 hours
+}
+
+export class FileCache {
+  private options: CacheOptions
+
+  constructor(options?: Partial<CacheOptions>) {
+    this.options = { ...DEFAULT_OPTIONS, ...options }
+  }
+
+  /**
+   * Sanitize cache key to create a valid filename
+   */
+  private sanitizeKey(key: string): string {
+    return key.replace(/[^a-zA-Z0-9_-]/g, "_")
+  }
+
+  /**
+   * Get the file path for a cache key
+   */
+  private getFilePath(key: string): string {
+    return path.join(this.options.cacheDir, `${this.sanitizeKey(key)}.json`)
+  }
+
+  /**
+   * Get cached data by key
+   * Returns null if not found or expired
+   */
+  async get<T>(key: string): Promise<T | null> {
+    const filePath = this.getFilePath(key)
+
+    try {
+      const content = await fs.readFile(filePath, "utf-8")
+      const entry: CacheEntry<T> = JSON.parse(content)
+
+      // Check if expired
+      if (Date.now() > entry.expiresAt) {
+        // Clean up expired entry
+        await this.delete(key)
+        return null
+      }
+
+      return entry.data
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Set cached data with optional custom TTL
+   */
+  async set<T>(key: string, data: T, options?: SetOptions): Promise<void> {
+    const ttl = options?.ttl ?? this.options.defaultTtl
+    const entry: CacheEntry<T> = {
+      data,
+      expiresAt: Date.now() + ttl,
+    }
+
+    const filePath = this.getFilePath(key)
+
+    // Ensure cache directory exists
+    await fs.mkdir(this.options.cacheDir, { recursive: true })
+
+    await fs.writeFile(filePath, JSON.stringify(entry), "utf-8")
+  }
+
+  /**
+   * Delete a specific cache entry
+   */
+  async delete(key: string): Promise<void> {
+    const filePath = this.getFilePath(key)
+
+    try {
+      await fs.unlink(filePath)
+    } catch {
+      // Ignore errors (file may not exist)
+    }
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  async clear(): Promise<void> {
+    try {
+      const files = await fs.readdir(this.options.cacheDir)
+      await Promise.all(files.map(file => fs.unlink(path.join(this.options.cacheDir, file))))
+    } catch {
+      // Ignore errors (directory may not exist)
+    }
+  }
+
+  /**
+   * Check if a valid (non-expired) cache entry exists
+   */
+  async has(key: string): Promise<boolean> {
+    const data = await this.get(key)
+    return data !== null
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,85 @@
+import { DevDocsClient } from "../services/devdocs-client.ts"
+import type { SearchOptions } from "../services/devdocs-client.ts"
+import type { FileCache } from "../services/file-cache.ts"
+
+export interface ListAvailableDocsInput {
+  filter?: string
+}
+
+export interface SearchDocsInput {
+  library: string
+  query: string
+  limit?: number
+  fuzzy?: boolean
+  threshold?: number
+}
+
+export interface GetDocPageInput {
+  library: string
+  path: string
+}
+
+export interface Tools {
+  listAvailableDocs: (input: ListAvailableDocsInput) => Promise<string>
+  searchDocs: (input: SearchDocsInput) => Promise<string>
+  getDocPage: (input: GetDocPageInput) => Promise<string>
+}
+
+export function createTools(cache: FileCache): Tools {
+  const client = new DevDocsClient({ cache })
+
+  return {
+    /**
+     * List all available documentation libraries
+     */
+    async listAvailableDocs(input: ListAvailableDocsInput): Promise<string> {
+      const docs = await client.listDocs(input.filter)
+
+      if (docs.length === 0) {
+        return input.filter ? `No documentation found matching "${input.filter}".` : "No documentation available."
+      }
+
+      const lines = docs.map(doc => {
+        const version = doc.version ? ` (${doc.version})` : ""
+        return `- **${doc.name}**${version}: \`${doc.slug}\``
+      })
+
+      const header = input.filter
+        ? `Found ${docs.length} documentation(s) matching "${input.filter}":\n\n`
+        : `Available documentation (${docs.length}):\n\n`
+
+      return header + lines.join("\n")
+    },
+
+    /**
+     * Search within a library's documentation
+     */
+    async searchDocs(input: SearchDocsInput): Promise<string> {
+      const options: SearchOptions = {
+        fuzzy: input.fuzzy,
+        threshold: input.threshold,
+      }
+      const results = await client.searchDocs(input.library, input.query, input.limit ?? 10, options)
+
+      if (results.length === 0) {
+        return `No results found for "${input.query}" in ${input.library} documentation.`
+      }
+
+      const lines = results.map((entry, index) => {
+        const scoreInfo = entry.score !== undefined ? ` (score: ${(1 - entry.score).toFixed(2)})` : ""
+        return `${index + 1}. **${entry.name}**${scoreInfo}\n   - Path: \`${entry.path}\`\n   - Type: ${entry.type}`
+      })
+
+      const searchMode = input.fuzzy !== false ? "fuzzy" : "exact"
+      return `Found ${results.length} result(s) for "${input.query}" in ${input.library} (${searchMode} search):\n\n${lines.join("\n\n")}`
+    },
+
+    /**
+     * Get a specific documentation page
+     */
+    async getDocPage(input: GetDocPageInput): Promise<string> {
+      const content = await client.getDocPage(input.library, input.path)
+      return content
+    },
+  }
+}

package/src/types/devdocs.ts

@@ -0,0 +1,51 @@
+/**
+ * DevDocs API Types
+ */
+
+/**
+ * Documentation entry from DevDocs docs.json
+ */
+export interface DevDocsDoc {
+  name: string
+  slug: string
+  type: string
+  version?: string
+  release?: string
+  mtime: number
+  db_size: number
+}
+
+/**
+ * Entry in a documentation index
+ */
+export interface DocEntry {
+  name: string
+  path: string
+  type: string
+}
+
+/**
+ * Documentation type/category
+ */
+export interface DocType {
+  name: string
+  count: number
+  slug: string
+}
+
+/**
+ * Documentation index response
+ */
+export interface DocIndex {
+  entries: DocEntry[]
+  types: DocType[]
+}
+
+/**
+ * Parsed library slug
+ */
+export interface ParsedSlug {
+  name: string
+  version?: string
+  slug: string
+}

package/src/utils/html-to-markdown.ts

@@ -0,0 +1,79 @@
+import TurndownService from "turndown"
+
+// Create and configure turndown instance
+const turndown = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-",
+  emDelimiter: "*",
+})
+
+// Custom rule for code blocks with language detection
+turndown.addRule("fencedCodeBlock", {
+  filter: (node): boolean => {
+    return node.nodeName === "PRE" && node.querySelector("code") !== null
+  },
+  replacement: (_content, node): string => {
+    const element = node as unknown as {
+      querySelector: (
+        s: string,
+      ) => { getAttribute: (a: string) => string | null; className?: string; textContent: string | null } | null
+      getAttribute: (a: string) => string | null
+    }
+    const codeElement = element.querySelector("code")
+    if (!codeElement) return ""
+
+    // Try to detect language from various attributes
+    const lang =
+      element.getAttribute("data-language") ||
+      codeElement.getAttribute("data-language") ||
+      codeElement.className?.match(/language-(\w+)/)?.[1] ||
+      ""
+
+    const code = codeElement.textContent || ""
+    return `\n\`\`\`${lang}\n${code.trim()}\n\`\`\`\n`
+  },
+})
+
+// Remove script tags
+turndown.addRule("removeScripts", {
+  filter: ["script"],
+  replacement: () => "",
+})
+
+// Remove style tags
+turndown.addRule("removeStyles", {
+  filter: ["style"],
+  replacement: () => "",
+})
+
+// Remove SVG elements (often used for icons in docs)
+turndown.addRule("removeSvg", {
+  filter: ["svg"],
+  replacement: () => "",
+})
+
+// Remove navigation elements
+turndown.addRule("removeNav", {
+  filter: ["nav"],
+  replacement: () => "",
+})
+
+/**
+ * Convert HTML to Markdown
+ * Optimized for DevDocs HTML structure
+ */
+export function htmlToMarkdown(html: string): string {
+  if (!html?.trim()) {
+    return ""
+  }
+
+  try {
+    const markdown = turndown.turndown(html)
+    // Clean up excessive newlines
+    return markdown.replace(/\n{3,}/g, "\n\n").trim()
+  } catch {
+    // If conversion fails, return empty string
+    return ""
+  }
+}