docs-agent 1.1.0

package/src/index.js

@@ -0,0 +1,49 @@
+import 'dotenv/config';
+import api from './api.js';
+import mcp from './mcp.js';
+import fs from 'fs';
+import path from 'path';
+
+if(process.env.API_DISABLED !== 'true'){
+  api.start(process.env.PORT || 3001);
+}
+
+if(process.env.MCP_DISABLED !== 'true'){
+  // Disable console logs because they write to std output stream which mcp client listens to
+  configureLogsForMcp();
+  // setupPersistentLogs('mcp.log');
+  mcp.start();
+}
+
+function configureLogsForMcp(){
+  console.log = console.error;
+  // console.error = () => {};
+  console.debug = console.error;
+  console.info = console.error;
+  console.warn = console.error;
+}
+
+function setupPersistentLogs(filename){
+  // Override console methods
+  console.log = logToFile;
+  console.error = logToFile;
+  console.warn = logToFile;
+  console.info = logToFile;
+  console.debug = logToFile;
+}
+
+function logToFile(...args) {
+  const logFile = path.join(process.cwd(), filename);
+  const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+  const message = args?.map(arg => {
+    if (typeof arg === 'object') {
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return '[Circular]';
+      }
+    }
+    return String(arg);
+  })?.join(' ') + '\n';
+  logStream.write(message);
+}

package/src/lib.js

@@ -0,0 +1,4 @@
+import DocsAgent from "./DocsAgent.js";
+
+export { DocsAgent };
+export default DocsAgent;

package/src/mcp.js

@@ -0,0 +1,268 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import DocsAgent from "./DocsAgent.js";
+import PROMPT_FOR_RELATED_FILES from "./config/prompt.relatedfiles.js";
+
+const mcpServer = new McpServer({
+    name: "docs-agent",
+    version: "1.4.0",
+});
+
+/**
+ * Tool to review docs quality following Diataxis framework
+ * @param {string} content - The complete docs page content to review
+ * @param {object} context - The context of the docs page
+ * @param {string} context.filename - The filename of the docs page
+ * @param {string} context.projectStructure - The project structure as folders/files hierarchy
+ * @param {string} context.relatedFilesContent - The contents of the related docs pages to the current page
+ * @returns {object} mcpResponse - The review results
+ * @property {object[]} mcpResponse.content - The review results
+ * @property {string} mcpResponse.content[].type - The type of the content e.g. text, code, image, etc.
+ * @property {string} mcpResponse.content[].text - The review results
+ * @example
+ * ```json
+ * {
+ *     "content": [{ "type": "text", "text": "The review results" }]
+ * }
+ * ```
+ */
+const reviewDocs = mcpServer.tool("reviewDocs",
+    "Review the docs page and return the review results.\n"+
+    "This tool reviews a specific docs page, and returns the review results.\n"+
+    "The projectStructure parameter is optional, but it is recommended to provide it to help the agent understand the project structure and improve the results.\n"+
+    "The relatedFiles parameter is optional, but it is recommended to improve the results.\n"+
+    PROMPT_FOR_RELATED_FILES + "\n",
+    {
+        filepath: z.string().describe("Absolute filepath of the docs page to improve"),
+        filename: z.string().describe("The relative path of the docs page from the root of the project").optional(),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy").optional(),
+        customInstructions: z.string().describe("Custom instructions for the docs improvement process.  Use this parameter cautiously as it might lead to limited scope of the changes.").optional(),
+        glossaryFile: z.string().describe("Filepath of the glossary file, containing a list of project-specific terms and their definitions, used for consistent and technically accurate documentation").optional(),
+        relatedFiles: z.array(z.string()).describe("Absolute filepaths of the docs pages that are related to the current page being improved. Usually the related files are the ones mentioned in the docs page content or the ones that are located under the same parent folder as the current page and related to the same topic. Order is important, the most relevant files should be the initial items in the array. Optional, but always recommened to at least include few related files.").optional(),
+        allowDisruptiveChanges: z.boolean().describe("Whether to allow disruptive changes such as restructuring the project files/folder structure").optional().default(false)
+    },
+    async (params) => {
+        log(`reviewDocs triggered for ${params?.filepath}`);
+        log(`Additional context ${params?.filename} ${params?.projectStructure}`);
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.review(null, {
+            filepath: params?.filepath,
+            filename: params?.filename,
+            projectStructure: params?.projectStructure,
+            customInstructions: params?.customInstructions,
+            glossaryFile: params?.glossaryFile,
+            relatedFiles: params?.relatedFiles,
+            allowDisruptiveChanges: params?.allowDisruptiveChanges
+        });
+        log(`Review results: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+);
+
+/**
+ * Tool to improve docs quality following Diataxis framework
+ * @param {string} content - The complete docs page content to improve
+ * @param {object} context - The context of the docs page
+ * @param {string} context.filename - The filename of the docs page
+ * @param {string} context.projectStructure - The project structure as folders/files hierarchy
+ * @param {string} context.relatedFilesContent - The contents of the related docs pages to the current page
+ * @returns {object} mcpResponse - The edited docs content
+ * @property {object[]} mcpResponse.content - The edited docs content
+ * @property {string} mcpResponse.content[].type - The type of the content e.g. text, code, image, etc.
+ * @property {string} mcpResponse.content[].text - The edited docs content
+ * @example
+ * ```json
+ * {
+ *     "content": [{ "type": "text", "text": "The edited docs content" }]
+ * }
+ * ```
+ */
+const improveDocsTool = mcpServer.tool("improveDocs",
+    "Improve docs quality following Diataxis framework, returns the edited docs content.\n"+
+    "This tool reviews a specific docs page, prioritizes the changes to be made, and returns the edited docs content.\n"+
+    "The projectStructure parameter is optional, but it is recommended to provide it to help the agent understand the project structure and improve the results.\n"+
+    "The relatedFiles parameter is optional, but it is recommended to improve the results.\n"+
+    "This tool returns the complete edited docs content, do not run editDocs tool again after this tool.\n"+
+    PROMPT_FOR_RELATED_FILES + "\n",
+    {
+        filepath: z.string().describe("Absolute filepath of the docs page to improve"),
+        filename: z.string().describe("The relative path of the docs page from the root of the project").optional(),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy").optional(),
+        customInstructions: z.string().describe("Custom instructions for the docs improvement process.  Use this parameter cautiously as it might lead to limited scope of the changes.").optional(),
+        glossaryFile: z.string().describe("Filepath of the glossary file, containing a list of project-specific terms and their definitions, used for consistent and technically accurate documentation").optional(),
+        relatedFiles: z.array(z.string()).describe("Absolute filepaths of the docs pages that are related to the current page being improved. Usually the related files are the ones mentioned in the docs page content or the ones that are located under the same parent folder as the current page and related to the same topic. Order is important, the most relevant files should be the initial items in the array. Optional, but always recommened to at least include few related files.").optional(),
+        allowDisruptiveChanges: z.boolean().describe("Whether to allow disruptive changes such as restructuring the project files/folder structure").optional().default(false)
+    },
+    async (params) => {
+        log(`improveDocs triggered for ${params?.filepath}`);
+        log(`Additional context ${params?.filename} ${params?.projectStructure}`);
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.reviewPrioritizeAndEdit(null, {
+            filepath: params?.filepath,
+            filename: params?.filename,
+            projectStructure: params?.projectStructure,
+            customInstructions: params?.customInstructions,
+            glossaryFile: params?.glossaryFile,
+            relatedFiles: params?.relatedFiles,
+            allowDisruptiveChanges: params?.allowDisruptiveChanges
+        });
+        log(`Edited docs content: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+);
+
+const editDocsTool = mcpServer.tool("editDocs",
+    "Edit the docs content according to the given specific editing instructions\n"+
+    "The edit plan parameter must be a detailed plan of the changes to be made to the documentation.\n"+
+    "This is not the right tool to choose when the goal also includes finding the gaps in the documentation. For the entire task to review and edit the docs, use the improveDocs tool instead.\n"+
+    PROMPT_FOR_RELATED_FILES + "\n",
+    {
+        filepath: z.string().describe("Absolute filepath of the docs page to edit"),
+        editPlan: z.string().describe("Specific changes to be made to the documentation. It must be highly detailed, specific, and with necessary citations and reasoning to support the changes."),
+        filename: z.string().describe("The relative path of the docs page from the root of the project").optional(),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy").optional(),
+        glossaryFile: z.string().describe("Filepath of the glossary file, containing a list of project-specific terms and their definitions, used for consistent and technically accurate documentation").optional(),
+        relatedFiles: z.array(z.string()).describe("Absolute filepaths of the docs pages that are related to the current page being reviewed/edited. Usually the related files are the ones mentioned in the docs page content or the ones that are located within the same parent folder as the current page and related to the same topic.").optional(),
+        customInstructions: z.string().describe("Custom instructions for the docs editing process").optional(),
+    },
+    async (params) => {
+        log(`editDocs triggered for ${params?.filepath}`);
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.edit(null, params?.editPlan, {
+                filepath: params?.filepath,
+                filename: params?.filename,
+                projectStructure: params?.projectStructure,
+                glossaryFile: params?.glossaryFile,
+                relatedFiles: params?.relatedFiles
+            },
+            params?.customInstructions
+        );
+        log(`Edited docs content: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+);
+
+const linkifyDocsTool = mcpServer.tool("linkifyDocs",
+    "Improve internal linking of the docs page to the related files and glossary concepts.\n"+
+    "Finds broken links, missing links, and adds internal links to the related files and glossary concepts.\n"+
+    "Including projectStructure and glossaryFile in the context will help improve the results dramatically.\n"+
+    "This tool returns the complete docs content with improved linking, do not run editDocs tool again after this tool.\n"+
+    PROMPT_FOR_RELATED_FILES + "\n",
+    {
+        filepath: z.string().describe("Absolute filepath of the docs page in which we need to add internal links"),
+        filename: z.string().describe("The relative path of the docs page from the root of the project").optional(),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy").optional(),
+        customInstructions: z.string().describe("Custom instructions for the docs internal linking process").optional(),
+        glossaryFile: z.string().describe("Filepath of the glossary file, containing a list of project-specific terms and their definitions, used for consistent and technically accurate documentation").optional(),
+        relatedFiles: z.array(z.string()).describe("Absolute filepaths of the docs pages that are related to the current page being reviewed/edited. Usually the related files are the ones mentioned in the docs page content or the ones that are located within the same parent folder as the current page and related to the same topic.").optional()
+    },
+    async (params) => {
+        log(`linkifyDocs triggered for ${params?.filepath}`);
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.linkify(null, { filepath: params?.filepath,
+            filename: params?.filename,
+            projectStructure: params?.projectStructure,
+            customInstructions: params?.customInstructions,
+            glossaryFile: params?.glossaryFile,
+            relatedFiles: params?.relatedFiles
+        });
+        log(`Linked docs content: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+);
+
+const auditDocsAgainstCodeTool = mcpServer.tool("auditDocsAgainstCode",
+    "Audit the docs against the source code to find the incorrect or outdated information. This tool checks the reference source code and verifies if the docs match the implementation in the codebase. It can also find missing critical technical information in the docs necessary for the goals of that particular docs page. This will take a really long time, sometimes even more than 10 minutes.",
+    {
+        docsContentFilePath: z.string().describe("Absolute filepath of the docs page to audit"),
+        repoUrl: z.string().describe("GitHub repository URL for the reference source code for the code audit"),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy of the repository").optional(),
+        customInstructions: z.string().describe("Custom instructions for the audit process").optional(),
+    },
+    async (params) => {
+        log(`auditDocsAgainstCode triggered for ${params?.docsContentFilePath}`);
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.auditDocsAgainstCode(
+            params?.docsContentFilePath,
+            {
+                repoUrl: params?.repoUrl,
+                projectStructure: params?.projectStructure
+            }, 
+            params?.customInstructions
+        );
+        log(`Audited docs against code: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+);
+
+/**
+ * @experimental This tool is experimental and might be dropped in the future.
+ */
+const generateReferenceDocsTool = mcpServer.tool("generateReferenceDocs",
+    "Generate reference docs for the given public interface file or GitHub repository\n"+
+    PROMPT_FOR_RELATED_FILES + "\n",
+    {
+        referenceSourceCodeFiles: z.array(z.string()).describe("Remote URLs of the necessary source code files to generate reference docs e.g. [\"https://raw.githubusercontent.com/rudderlabs/analytics-go/refs/heads/master/analytics.go\", \"https://raw.githubusercontent.com/rudderlabs/analytics-go/refs/heads/master/config.go\"]"),
+        repoUrl: z.string().describe("GitHub repository URL").optional(),
+        interfaceType: z.enum(["library", "http", "mcp", "cli", "rpc", "other"]).describe("Type of reference docs, how the code exposes its interfaces to the outside world").optional(),
+        relatedFileUrls: z.array(z.string()).describe("Remote URLs of the code files that are related to the given mainPublicInterfaceFileUrl").optional(),
+        projectStructure: z.string().describe("A nested markdown list of the project structure showing the folders/files hierarchy of the repository").optional(),
+        customInstructions: z.string().describe("Custom instructions for the reference docs generation process").optional(),
+        knowledgeBase: z.string().describe("Knowledge base such as higher level architecture of the parent project, this is only to develop understanding of the context of the current codebase. Do not include this in the reference docs, this is already published on docs website").optional(),
+    },
+    async (params) => {
+        log(`generateReferenceDocs triggered for ${params?.referenceSourceCodeFiles}`);  
+        const docsAgent = new DocsAgent('mcp');
+        const response = await docsAgent.generateReferenceDocs(params?.referenceSourceCodeFiles, {
+            interfaceType: params?.interfaceType,
+            relatedFileUrls: params?.relatedFileUrls,
+            repoUrl: params?.repoUrl,
+            projectStructure: params?.projectStructure,
+            knowledgeBase: params?.knowledgeBase
+        }, params?.customInstructions);
+        log(`Generated reference docs: ${response}`);
+        return {
+            content: [{ type: "text", text: String(response) }]
+        };
+    }
+).disable();
+
+async function start() {
+    // Start receiving messages on stdin and sending messages on stdout
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+    log("MCP Server started successfully");
+    log("reviewDocs tool " + (reviewDocs?.enabled ? "enabled" : "disabled") + "\nMetadata: "+reviewDocs?.metadata);
+    log("improveDocs tool " + (improveDocsTool?.enabled ? "enabled" : "disabled") + "\nMetadata: "+improveDocsTool?.metadata);
+    log("editDocs tool " + (editDocsTool?.enabled ? "enabled" : "disabled") + "\nMetadata: "+editDocsTool?.metadata);
+    log("linkifyDocs tool " + (linkifyDocsTool?.enabled ? "enabled" : "disabled") + "\nMetadata: "+linkifyDocsTool?.metadata);
+    log("auditDocsAgainstCode tool " + (auditDocsAgainstCodeTool?.enabled ? "enabled" : "disabled") + "\nMetadata: "+auditDocsAgainstCodeTool?.metadata);
+    log("generateReferenceDocs tool " + (generateReferenceDocsTool?.enabled ? "enabled" : "disabled") + "\nMetadata: "+generateReferenceDocsTool?.metadata);
+}
+
+function log(message, level = "info"){
+    if(level === "error"){
+        console.error(message);
+    } else {
+        console.log(message);
+    }
+    if(process.env.NODE_ENV === "production"){
+        // Do not send logs to client in production
+        return;
+    }
+    //TODO: Send logs to client.
+    // `mcpServer.server.sendLoggingMessage` is throwing error as of now - "server does not support logging"
+}
+
+export default { start };