openclaw-docs-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+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,174 @@
+# openclaw-docs-mcp
+
+[![npm version](https://badge.fury.io/js/openclaw-docs-mcp.svg)](https://www.npmjs.com/package/openclaw-docs-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Model Context Protocol (MCP) server for searching and retrieving documentation from [OpenClaw](https://docs.openclaw.ai/).
+
+## Features
+
+- 🔍 **Search documentation** - Full-text search across all OpenClaw docs
+- 📄 **Retrieve pages** - Get complete content of any documentation page
+- 📋 **List all pages** - Browse the full documentation structure
+- ⚡ **Fast caching** - Built-in caching for improved performance
+
+## Installation
+
+### Global Installation (recommended)
+
+```bash
+npm install -g openclaw-docs-mcp
+```
+
+### Local Installation
+
+```bash
+npm install openclaw-docs-mcp
+```
+
+## Usage
+
+### As MCP Server
+
+Run directly:
+
+```bash
+openclaw-docs-mcp
+```
+
+Or with npx:
+
+```bash
+npx openclaw-docs-mcp
+```
+
+### VS Code Configuration
+
+Add to your VS Code `mcp.json` (`~/.config/Code/User/mcp.json` or `%APPDATA%\Code\User\mcp.json`):
+
+```json
+{
+  "servers": {
+    "openclaw-docs": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "openclaw-docs-mcp"]
+    }
+  }
+}
+```
+
+For WSL users on Windows:
+
+```json
+{
+  "servers": {
+    "openclaw-docs": {
+      "type": "stdio",
+      "command": "wsl",
+      "args": ["-e", "npx", "-y", "openclaw-docs-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "openclaw-docs": {
+      "command": "npx",
+      "args": ["-y", "openclaw-docs-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### search_openclaw_docs
+
+Search OpenClaw documentation for information about a topic.
+
+**Parameters:**
+- `query` (string, required): Search query (e.g., "gateway configuration", "telegram channel")
+- `maxResults` (number, optional): Maximum results to return (default: 5, max: 20)
+
+**Example:**
+```json
+{
+  "name": "search_openclaw_docs",
+  "arguments": {
+    "query": "telegram channel setup",
+    "maxResults": 5
+  }
+}
+```
+
+### get_openclaw_doc_page
+
+Get the full content of a specific documentation page.
+
+**Parameters:**
+- `path` (string, required): Page path (e.g., "/gateway/configuration", "/channels/telegram")
+
+**Example:**
+```json
+{
+  "name": "get_openclaw_doc_page",
+  "arguments": {
+    "path": "/gateway/configuration"
+  }
+}
+```
+
+### list_openclaw_doc_pages
+
+List all available documentation pages from the sitemap.
+
+**Parameters:** None
+
+**Example:**
+```json
+{
+  "name": "list_openclaw_doc_pages",
+  "arguments": {}
+}
+```
+
+## How It Works
+
+1. Fetches the sitemap from `https://docs.openclaw.ai/sitemap.xml`
+2. Parses HTML content using Cheerio to extract text
+3. Performs keyword-based relevance scoring for search results
+4. Caches results for 5 minutes to improve performance
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/openclaw/openclaw-docs-mcp.git
+cd openclaw-docs-mcp
+
+# Install dependencies
+npm install
+
+# Run locally
+node index.js
+
+# Test tools/list
+echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | node index.js
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related
+
+- [OpenClaw Documentation](https://docs.openclaw.ai/)
+- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
+- [Model Context Protocol](https://modelcontextprotocol.io/)

package/index.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+
+/**
+ * OpenClaw Docs MCP Server
+ * 
+ * A Model Context Protocol server that provides tools to search and retrieve
+ * documentation from https://docs.openclaw.ai/
+ * 
+ * Features:
+ * - Fetches sitemap to get all documentation URLs
+ * - Searches documentation content
+ * - Retrieves specific documentation pages
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import fetch from "node-fetch";
+import { parseStringPromise } from "xml2js";
+import * as cheerio from "cheerio";
+
+const DOCS_BASE_URL = "https://docs.openclaw.ai";
+const SITEMAP_URL = `${DOCS_BASE_URL}/sitemap.xml`;
+
+// Cache for sitemap URLs and page content
+let sitemapCache = null;
+let sitemapCacheTime = 0;
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+// Content cache for faster repeated searches
+const contentCache = new Map();
+
+/**
+ * Fetch and parse the sitemap to get all documentation URLs
+ */
+async function fetchSitemap() {
+  const now = Date.now();
+  if (sitemapCache && now - sitemapCacheTime < CACHE_TTL) {
+    return sitemapCache;
+  }
+
+  try {
+    const response = await fetch(SITEMAP_URL);
+    const xml = await response.text();
+    const result = await parseStringPromise(xml);
+    
+    const urls = result.urlset.url.map((entry) => ({
+      loc: entry.loc[0],
+      lastmod: entry.lastmod?.[0] || null,
+    }));
+
+    sitemapCache = urls;
+    sitemapCacheTime = now;
+    return urls;
+  } catch (error) {
+    console.error("Error fetching sitemap:", error);
+    throw new Error(`Failed to fetch sitemap: ${error.message}`);
+  }
+}
+
+/**
+ * Fetch and parse a documentation page to extract text content
+ */
+async function fetchPageContent(url) {
+  // Check cache first
+  if (contentCache.has(url)) {
+    return contentCache.get(url);
+  }
+
+  try {
+    const response = await fetch(url);
+    const html = await response.text();
+    const $ = cheerio.load(html);
+
+    // Remove script and style elements
+    $("script, style, nav, header, footer, .sidebar, .toc").remove();
+
+    // Try to find the main content area
+    let content = "";
+    const contentSelectors = [
+      "article",
+      ".markdown",
+      ".mdx-content",
+      "main",
+      "#content-container",
+      ".prose",
+    ];
+
+    for (const selector of contentSelectors) {
+      const el = $(selector);
+      if (el.length > 0) {
+        content = el.text();
+        break;
+      }
+    }
+
+    if (!content) {
+      content = $("body").text();
+    }
+
+    // Clean up whitespace
+    content = content
+      .replace(/\s+/g, " ")
+      .replace(/\n\s*\n/g, "\n")
+      .trim();
+
+    // Extract title
+    const title = $("h1").first().text().trim() || 
+                  $("title").text().trim().replace(" | OpenClaw Docs", "") ||
+                  url.split("/").pop();
+
+    // Extract description/summary (first paragraph or meta description)
+    const description = $('meta[name="description"]').attr("content") ||
+                       $("p").first().text().trim().slice(0, 200);
+
+    const pageData = {
+      url,
+      title,
+      description,
+      content: content.slice(0, 50000), // Limit content size
+      fetchedAt: Date.now(),
+    };
+
+    // Cache the result
+    contentCache.set(url, pageData);
+
+    return pageData;
+  } catch (error) {
+    console.error(`Error fetching page ${url}:`, error);
+    throw new Error(`Failed to fetch page: ${error.message}`);
+  }
+}
+
+/**
+ * Search documentation pages for a query
+ */
+async function searchDocs(query, maxResults = 10) {
+  const urls = await fetchSitemap();
+  const queryLower = query.toLowerCase();
+  const queryTerms = queryLower.split(/\s+/).filter(t => t.length > 2);
+  
+  const results = [];
+
+  // First, try to find matches based on URL/path
+  const urlMatches = urls.filter(({ loc }) => {
+    const path = loc.replace(DOCS_BASE_URL, "").toLowerCase();
+    return queryTerms.some(term => path.includes(term));
+  });
+
+  // Prioritize URL matches, then fetch content for the most relevant
+  const urlsToCheck = [
+    ...urlMatches.slice(0, Math.min(10, maxResults)),
+    ...urls.filter(u => !urlMatches.includes(u)).slice(0, 20),
+  ].slice(0, 30);
+
+  // Fetch and search content in parallel (limited concurrency)
+  const batchSize = 5;
+  for (let i = 0; i < urlsToCheck.length && results.length < maxResults; i += batchSize) {
+    const batch = urlsToCheck.slice(i, i + batchSize);
+    const pagePromises = batch.map(async ({ loc }) => {
+      try {
+        const page = await fetchPageContent(loc);
+        const contentLower = page.content.toLowerCase();
+        const titleLower = page.title.toLowerCase();
+
+        // Calculate relevance score
+        let score = 0;
+        for (const term of queryTerms) {
+          if (titleLower.includes(term)) score += 10;
+          if (page.url.toLowerCase().includes(term)) score += 5;
+          
+          // Count occurrences in content
+          const regex = new RegExp(term, "gi");
+          const matches = page.content.match(regex);
+          if (matches) score += Math.min(matches.length, 10);
+        }
+
+        if (score > 0) {
+          return { ...page, score };
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    });
+
+    const batchResults = await Promise.all(pagePromises);
+    for (const result of batchResults) {
+      if (result && results.length < maxResults) {
+        results.push(result);
+      }
+    }
+  }
+
+  // Sort by relevance score
+  results.sort((a, b) => b.score - a.score);
+
+  return results.slice(0, maxResults);
+}
+
+/**
+ * Get a specific documentation page by path
+ */
+async function getDocPage(path) {
+  // Normalize path
+  if (!path.startsWith("/")) {
+    path = "/" + path;
+  }
+  if (path.endsWith("/")) {
+    path = path.slice(0, -1);
+  }
+
+  const url = `${DOCS_BASE_URL}${path}`;
+  return await fetchPageContent(url);
+}
+
+/**
+ * List all documentation pages from sitemap
+ */
+async function listDocPages() {
+  const urls = await fetchSitemap();
+  return urls.map(({ loc, lastmod }) => ({
+    path: loc.replace(DOCS_BASE_URL, "") || "/",
+    url: loc,
+    lastmod,
+  }));
+}
+
+// Create the MCP server
+const server = new Server(
+  {
+    name: "openclaw-docs-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "search_openclaw_docs",
+        description:
+          "Search OpenClaw documentation for information about a topic. Returns relevant documentation pages with their content. Use this to find information about OpenClaw features, configuration, CLI commands, channels, plugins, and more.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description:
+                "The search query. Can include multiple keywords like 'gateway configuration' or 'telegram channel setup'",
+            },
+            maxResults: {
+              type: "number",
+              description:
+                "Maximum number of results to return (default: 5, max: 20)",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "get_openclaw_doc_page",
+        description:
+          "Get the full content of a specific OpenClaw documentation page by its path. Use this when you know the exact page you want to read.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description:
+                "The documentation page path, e.g., '/gateway/configuration', '/channels/telegram', '/cli/setup'",
+            },
+          },
+          required: ["path"],
+        },
+      },
+      {
+        name: "list_openclaw_doc_pages",
+        description:
+          "List all available OpenClaw documentation pages. Returns the sitemap with page paths and last modified dates. Useful for exploring the documentation structure.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "search_openclaw_docs": {
+        const query = args.query;
+        const maxResults = Math.min(args.maxResults || 5, 20);
+        
+        const results = await searchDocs(query, maxResults);
+        
+        if (results.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No documentation found for query: "${query}"\n\nTry different keywords or use list_openclaw_doc_pages to see available pages.`,
+              },
+            ],
+          };
+        }
+
+        const formattedResults = results.map((r, i) => {
+          // Extract relevant snippet around the first query match
+          const queryTerms = query.toLowerCase().split(/\s+/);
+          let snippet = r.description;
+          
+          for (const term of queryTerms) {
+            const idx = r.content.toLowerCase().indexOf(term);
+            if (idx !== -1) {
+              const start = Math.max(0, idx - 100);
+              const end = Math.min(r.content.length, idx + 300);
+              snippet = (start > 0 ? "..." : "") + 
+                       r.content.slice(start, end) + 
+                       (end < r.content.length ? "..." : "");
+              break;
+            }
+          }
+
+          return `## ${i + 1}. ${r.title}\n**URL:** ${r.url}\n**Relevance Score:** ${r.score}\n\n${snippet}\n`;
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# Search Results for "${query}"\n\nFound ${results.length} relevant pages:\n\n${formattedResults.join("\n---\n\n")}`,
+            },
+          ],
+        };
+      }
+
+      case "get_openclaw_doc_page": {
+        const path = args.path;
+        const page = await getDocPage(path);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# ${page.title}\n\n**URL:** ${page.url}\n\n---\n\n${page.content}`,
+            },
+          ],
+        };
+      }
+
+      case "list_openclaw_doc_pages": {
+        const pages = await listDocPages();
+        
+        // Group by section
+        const sections = {};
+        for (const page of pages) {
+          const parts = page.path.split("/").filter(Boolean);
+          const section = parts[0] || "root";
+          if (!sections[section]) {
+            sections[section] = [];
+          }
+          sections[section].push(page);
+        }
+
+        let output = "# OpenClaw Documentation Pages\n\n";
+        output += `Total pages: ${pages.length}\n\n`;
+
+        for (const [section, sectionPages] of Object.entries(sections).sort()) {
+          output += `## ${section}\n`;
+          for (const page of sectionPages.sort((a, b) => a.path.localeCompare(b.path))) {
+            output += `- [${page.path || "/"}](${page.url})`;
+            if (page.lastmod) {
+              output += ` (${page.lastmod.split("T")[0]})`;
+            }
+            output += "\n";
+          }
+          output += "\n";
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: output,
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("OpenClaw Docs MCP Server running on stdio");
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "openclaw-docs-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for searching OpenClaw documentation at docs.openclaw.ai",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "openclaw-docs-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openclaw",
+    "documentation",
+    "search",
+    "ai",
+    "llm"
+  ],
+  "author": "OpenClaw Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw-docs-mcp"
+  },
+  "homepage": "https://docs.openclaw.ai",
+  "bugs": {
+    "url": "https://github.com/openclaw/openclaw-docs-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "cheerio": "^1.0.0",
+    "node-fetch": "^3.3.2",
+    "xml2js": "^0.6.2"
+  }
+}