Add rush docs mcp plugin (#5245)

L-Qun · octogonz · web-flow · commit fd1a41bd41d6 · 2025-06-13T10:04:45.000-07:00
* feat: rush docs plugin

* feat: rush docs plugin

* rush change

* fix ci

* Update common/changes/@rushstack/mcp-server/feat-add-new-mcp-plugin_2025-06-09-13-09.json

---------

Co-authored-by: Pete Gonzalez &lt;4673363+octogonz@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -103,6 +103,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/rush-plugins/rush-bridge-cache-plugin](./rush-plugins/rush-bridge-cache-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-bridge-cache-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-bridge-cache-plugin) | | [@rushstack/rush-bridge-cache-plugin](https://www.npmjs.com/package/@rushstack/rush-bridge-cache-plugin) |
 | [/rush-plugins/rush-buildxl-graph-plugin](./rush-plugins/rush-buildxl-graph-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-buildxl-graph-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-buildxl-graph-plugin) | | [@rushstack/rush-buildxl-graph-plugin](https://www.npmjs.com/package/@rushstack/rush-buildxl-graph-plugin) |
 | [/rush-plugins/rush-http-build-cache-plugin](./rush-plugins/rush-http-build-cache-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-http-build-cache-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-http-build-cache-plugin) | | [@rushstack/rush-http-build-cache-plugin](https://www.npmjs.com/package/@rushstack/rush-http-build-cache-plugin) |
+| [/rush-plugins/rush-mcp-docs-plugin](./rush-plugins/rush-mcp-docs-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-mcp-docs-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-mcp-docs-plugin) | [changelog](./rush-plugins/rush-mcp-docs-plugin/CHANGELOG.md) | [@rushstack/rush-mcp-docs-plugin](https://www.npmjs.com/package/@rushstack/rush-mcp-docs-plugin) |
 | [/rush-plugins/rush-redis-cobuild-plugin](./rush-plugins/rush-redis-cobuild-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-redis-cobuild-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-redis-cobuild-plugin) | | [@rushstack/rush-redis-cobuild-plugin](https://www.npmjs.com/package/@rushstack/rush-redis-cobuild-plugin) |
 | [/rush-plugins/rush-resolver-cache-plugin](./rush-plugins/rush-resolver-cache-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-resolver-cache-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-resolver-cache-plugin) | | [@rushstack/rush-resolver-cache-plugin](https://www.npmjs.com/package/@rushstack/rush-resolver-cache-plugin) |
 | [/rush-plugins/rush-serve-plugin](./rush-plugins/rush-serve-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-serve-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Frush-serve-plugin) | | [@rushstack/rush-serve-plugin](https://www.npmjs.com/package/@rushstack/rush-serve-plugin) |
diff --git a/apps/rush-mcp-server/.npmignore b/apps/rush-mcp-server/.npmignore
@@ -21,8 +21,6 @@
 /lib-*/**/test/
 *.test.js
 
-!*.mock.json
-
 # NOTE: These don't need to be specified, because NPM includes them automatically.
 #
 # package.json
diff --git a/apps/rush-mcp-server/src/server.ts b/apps/rush-mcp-server/src/server.ts
@@ -8,8 +8,7 @@ import {
   RushMigrateProjectTool,
   RushCommandValidatorTool,
   RushWorkspaceDetailsTool,
-  RushProjectDetailsTool,
-  RushDocsTool
+  RushProjectDetailsTool
 } from './tools';
 import { RushMcpPluginLoader } from './pluginFramework/RushMcpPluginLoader';
 
@@ -41,7 +40,6 @@ export class RushMCPServer extends McpServer {
     this._tools.push(new RushCommandValidatorTool());
     this._tools.push(new RushWorkspaceDetailsTool());
     this._tools.push(new RushProjectDetailsTool());
-    this._tools.push(new RushDocsTool());
   }
 
   private _registerTools(): void {
diff --git a/apps/rush-mcp-server/src/tools/index.ts b/apps/rush-mcp-server/src/tools/index.ts
@@ -7,4 +7,3 @@ export * from './project-details.tool';
 export * from './rush-command-validator.tool';
 export * from './workspace-details';
 export * from './conflict-resolver.tool';
-export * from './docs.tool';
diff --git a/common/changes/@rushstack/mcp-server/feat-add-new-mcp-plugin_2025-06-09-13-09.json b/common/changes/@rushstack/mcp-server/feat-add-new-mcp-plugin_2025-06-09-13-09.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/mcp-server",
+      "comment": "Move the `rush docs` tool to a plugin package `@rushstack/rush-mcp-docs-plugin`",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/mcp-server"
+}
diff --git a/common/changes/@rushstack/rush-mcp-docs-plugin/feat-add-new-mcp-plugin_2025-06-09-13-09.json b/common/changes/@rushstack/rush-mcp-docs-plugin/feat-add-new-mcp-plugin_2025-06-09-13-09.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/rush-mcp-docs-plugin",
+      "comment": "Add rush docs mcp plugin",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/rush-mcp-docs-plugin"
+}
diff --git a/common/config/rush/nonbrowser-approved-packages.json b/common/config/rush/nonbrowser-approved-packages.json
@@ -232,7 +232,7 @@
     },
     {
       "name": "@rushstack/mcp-server",
-      "allowedCategories": [ "tests" ]
+      "allowedCategories": [ "libraries", "tests" ]
     },
     {
       "name": "@rushstack/module-minifier",
@@ -494,6 +494,10 @@
       "name": "buttono",
       "allowedCategories": [ "tests" ]
     },
+    {
+      "name": "chokidar",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "cli-table",
       "allowedCategories": [ "libraries" ]
@@ -662,10 +666,6 @@
       "name": "https-proxy-agent",
       "allowedCategories": [ "libraries" ]
     },
-    {
-      "name": "chokidar",
-      "allowedCategories": [ "libraries" ]
-    },
     {
       "name": "ignore",
       "allowedCategories": [ "libraries" ]
diff --git a/common/config/subspaces/default/pnpm-lock.yaml b/common/config/subspaces/default/pnpm-lock.yaml
diff --git a/rush-plugins/rush-mcp-docs-plugin/.eslintrc.js b/rush-plugins/rush-mcp-docs-plugin/.eslintrc.js
@@ -0,0 +1,13 @@
+// This is a workaround for https://github.com/eslint/eslint/issues/3458
+require('local-eslint-config/patch/modern-module-resolution');
+// This is a workaround for https://github.com/microsoft/rushstack/issues/3021
+require('local-eslint-config/patch/custom-config-package-names');
+
+module.exports = {
+  extends: [
+    'local-eslint-config/profile/node',
+    'local-eslint-config/mixins/friendly-locals',
+    'local-eslint-config/mixins/tsdoc'
+  ],
+  parserOptions: { tsconfigRootDir: __dirname }
+};
diff --git a/rush-plugins/rush-mcp-docs-plugin/.npmignore b/rush-plugins/rush-mcp-docs-plugin/.npmignore
@@ -0,0 +1,37 @@
+# THIS IS A STANDARD TEMPLATE FOR .npmignore FILES IN THIS REPO.
+
+# Ignore all files by default, to avoid accidentally publishing unintended files.
+*
+
+# Use negative patterns to bring back the specific things we want to publish.
+!/bin/**
+!/lib/**
+!/lib-*/**
+!/dist/**
+
+!CHANGELOG.md
+!CHANGELOG.json
+!heft-plugin.json
+!rush-plugin-manifest.json
+!ThirdPartyNotice.txt
+
+# Ignore certain patterns that should not get published.
+/dist/*.stats.*
+/lib/**/test/
+/lib-*/**/test/
+*.test.js
+
+# NOTE: These don't need to be specified, because NPM includes them automatically.
+#
+# package.json
+# README.md
+# LICENSE
+
+# ---------------------------------------------------------------------------
+# DO NOT MODIFY ABOVE THIS LINE!  Add any project-specific overrides below.
+# ---------------------------------------------------------------------------
+
+!rush-mcp-plugin.json
+!*.schema.json
+
+!*.mock.json
diff --git a/rush-plugins/rush-mcp-docs-plugin/LICENSE b/rush-plugins/rush-mcp-docs-plugin/LICENSE
@@ -0,0 +1,24 @@
+@rushstack/rush-mcp-docs-plugin
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+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.
diff --git a/rush-plugins/rush-mcp-docs-plugin/README.md b/rush-plugins/rush-mcp-docs-plugin/README.md
@@ -0,0 +1,3 @@
+# @rushstack/rush-mcp-docs-plugin
+
+The @rushstack/rush-mcp-docs-plugin package provides a documentation query tool for Rush.
diff --git a/rush-plugins/rush-mcp-docs-plugin/config/rig.json b/rush-plugins/rush-mcp-docs-plugin/config/rig.json
@@ -0,0 +1,7 @@
+{
+  // The "rig.json" file directs tools to look for their config files in an external package.
+  // Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "local-node-rig"
+}
diff --git a/rush-plugins/rush-mcp-docs-plugin/package.json b/rush-plugins/rush-mcp-docs-plugin/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@rushstack/rush-mcp-docs-plugin",
+  "version": "0.0.0",
+  "description": "Docs plugin for @rushstack/mcp-server",
+  "repository": {
+    "url": "https://github.com/microsoft/rushstack.git",
+    "type": "git",
+    "directory": "rush-plugins/rush-mcp-docs-plugin"
+  },
+  "homepage": "https://rushjs.io",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  },
+  "dependencies": {
+    "@rushstack/node-core-library": "workspace:*",
+    "@rushstack/mcp-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "workspace:*",
+    "local-node-rig": "workspace:*",
+    "local-eslint-config": "workspace:*"
+  }
+}
diff --git a/rush-plugins/rush-mcp-docs-plugin/rush-mcp-plugin.json b/rush-plugins/rush-mcp-docs-plugin/rush-mcp-plugin.json
@@ -0,0 +1,24 @@
+/**
+ * Every plugin package must contain a "rush-mcp-plugin.json" manifest in the top-level folder
+ * (next to package.json).
+ */
+{
+  /**
+   * A name that uniquely identifies your plugin.  Generally this should be the same name as
+   * the NPM package.  If two NPM packages have the same pluginName, they cannot be loaded together.
+   */
+  "pluginName": "rush-mcp-docs-plugin",
+
+  /**
+   * (OPTIONAL) Indicates that your plugin accepts a config file.  The MCP server will load this
+   * file and provide it to the plugin.
+   *
+   * The config file path will be `<rush-repo>/common/config/rush-mcp/<plugin-name>.json`.
+   */
+  // "configFileSchema": "./lib/rush-mcp-example-plugin.schema.json",
+
+  /**
+   * The entry point, whose default export should be a class that implements
+   */
+  "entryPoint": "./lib/index.js"
+}
diff --git a/rush-plugins/rush-mcp-docs-plugin/src/DocsPlugin.ts b/rush-plugins/rush-mcp-docs-plugin/src/DocsPlugin.ts
@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IRushMcpPlugin, RushMcpPluginSession } from '@rushstack/mcp-server';
+import { DocsTool } from './DocsTool';
+
+export interface IDocsPluginConfigFile {}
+
+export class DocsPlugin implements IRushMcpPlugin {
+  public session: RushMcpPluginSession;
+  public configFile: IDocsPluginConfigFile | undefined = undefined;
+
+  public constructor(session: RushMcpPluginSession, configFile: IDocsPluginConfigFile | undefined) {
+    this.session = session;
+    this.configFile = configFile;
+  }
+
+  public async onInitializeAsync(): Promise<void> {
+    this.session.registerTool(
+      {
+        toolName: 'rush_docs',
+        description:
+          'Search and retrieve relevant sections from the official Rush documentation based on user queries.'
+      },
+      new DocsTool(this)
+    );
+  }
+}
diff --git a/rush-plugins/rush-mcp-docs-plugin/src/DocsTool.ts b/rush-plugins/rush-mcp-docs-plugin/src/DocsTool.ts
@@ -1,11 +1,11 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { z } from 'zod';
+import type { IRushMcpTool, RushMcpPluginSession, CallToolResult, zodModule } from '@rushstack/mcp-server';
 import { JsonFile } from '@rushstack/node-core-library';
 import path from 'path';
 
-import { BaseTool, type CallToolResult } from './base.tool';
+import type { DocsPlugin } from './DocsPlugin';
 
 interface IDocsResult {
   query: string;
@@ -17,15 +17,22 @@ interface IDocsResult {
   searchTimeMs: number;
 }
 
-export class RushDocsTool extends BaseTool {
-  public constructor() {
-    super({
-      name: 'rush_docs',
-      description:
-        'Search and retrieve relevant sections from the official Rush documentation based on user queries.',
-      schema: {
-        userQuery: z.string().describe('The user query to search for relevant documentation sections.')
-      }
+export class DocsTool implements IRushMcpTool<DocsTool['schema']> {
+  public readonly plugin: DocsPlugin;
+  public readonly session: RushMcpPluginSession;
+
+  public constructor(plugin: DocsPlugin) {
+    this.plugin = plugin;
+    this.session = plugin.session;
+  }
+
+  // ZOD relies on type inference generate a messy expression in the .d.ts file
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+  public get schema() {
+    const zod: typeof zodModule = this.session.zod;
+
+    return zod.object({
+      userQuery: zod.string().describe('The user query to search for relevant documentation sections.')
     });
   }
 
@@ -34,7 +41,7 @@ export class RushDocsTool extends BaseTool {
     const startTime: number = Date.now();
 
     const results: IDocsResult['results'] = JsonFile.load(
-      path.join(__dirname, '../rush-doc-fragment.mock.json')
+      path.join(__dirname, './rush-doc-fragment.mock.json')
     );
 
     return {
@@ -45,7 +52,7 @@ export class RushDocsTool extends BaseTool {
     };
   }
 
-  public async executeAsync({ userQuery }: { userQuery: string }): Promise<CallToolResult> {
+  public async executeAsync({ userQuery }: zodModule.infer<DocsTool['schema']>): Promise<CallToolResult> {
     const docSearchResult: IDocsResult = this._searchDocs(userQuery);
 
     return {
diff --git a/rush-plugins/rush-mcp-docs-plugin/src/index.ts b/rush-plugins/rush-mcp-docs-plugin/src/index.ts
@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { RushMcpPluginSession, RushMcpPluginFactory } from '@rushstack/mcp-server';
+import { DocsPlugin, type IDocsPluginConfigFile } from './DocsPlugin';
+
+function createPlugin(
+  session: RushMcpPluginSession,
+  configFile: IDocsPluginConfigFile | undefined
+): DocsPlugin {
+  return new DocsPlugin(session, configFile);
+}
+
+export default createPlugin satisfies RushMcpPluginFactory<IDocsPluginConfigFile>;
diff --git a/rush-plugins/rush-mcp-docs-plugin/src/rush-doc-fragment.mock.json b/rush-plugins/rush-mcp-docs-plugin/src/rush-doc-fragment.mock.json
diff --git a/rush-plugins/rush-mcp-docs-plugin/tsconfig.json b/rush-plugins/rush-mcp-docs-plugin/tsconfig.json
@@ -0,0 +1,3 @@
+{
+  "extends": "./node_modules/local-node-rig/profiles/default/tsconfig-base.json"
+}
diff --git a/rush.json b/rush.json
@@ -1432,6 +1432,12 @@
       "projectFolder": "webpack/webpack5-localization-plugin",
       "reviewCategory": "libraries",
       "shouldPublish": true
+    },
+    {
+      "packageName": "@rushstack/rush-mcp-docs-plugin",
+      "projectFolder": "rush-plugins/rush-mcp-docs-plugin",
+      "reviewCategory": "libraries",
+      "shouldPublish": true
     }
   ]
 }

Original file line number	Diff line number	Diff line change
`@@ -21,8 +21,6 @@`
`21`	`21`	`/lib-/*/test/`
`22`	`22`	`*.test.js`
`23`	`23`
`24`		`-!*.mock.json`
`25`		`-`
`26`	`24`	`# NOTE: These don't need to be specified, because NPM includes them automatically.`
`27`	`25`	`#`
`28`	`26`	`# package.json`