[mcp-server] Introduce a plugin system for custom MCP tools

[octogonz]

@L-Qun

Here's a design sketch for a plugin system for @rushstack/mcp-server.

Basic ideas:

• An MCP plugin is an NPM package with an rush-mcp-plugin.json manifest file in its root folder.
  Example: build-tests/rush-mcp-example-plugin/rush-mcp-plugin.json

• The plugin can optionally define a JSON config file with a schema. Its name will be <rush-repo>/common/config/rush-mcp/<plugin-name>.json. This way each monorepo can configure its MCP plugins differently, for example different POC contact emails for each monorepo.

• @rushstack/mcp-server manages loading of plugins: (1) ensure the autoinstaller is installed, (2) use the manifest to find the entry point, (3) if there is a config file, load it and validate its JSON schema, (4) call createPlugin() to create the plugin class, (5) finally call onInitializeAsync() so the plugin can initialize itself.

• It took me a while to realize that plugins can add/remove MCP tools interactively, as well as MCP resources etc. All the MCP API stuff will be exposed via RushMcpPluginSession. The plugin calls it like this.session.registerTool({ toolName: 'state_capital' }, new StateCapitalTool(this));.

• The key design requirements motivating RushMcpPluginSession:

  • @rushstack/mcp-server is a devDependency for plugins, NOT a regular dependency.
  • In other words, plugins must always use import type when importing from @rushstack/mcp-server.
  • Similarly, plugins do NOT need to depend on zod or @modelcontextprotocol/sdk. This ensures multiple plugins can be loaded without doppelgangers or dependency hell, and it will also greatly improve the backwards compatibility story.
  • Lastly, although official MCP already provides an SDK for TypeScript, this package is really about protocol interactions. It is missing a clear story for (1) managing dependencies between plugins, as well as (2) sharing Rush caches and resources between plugins
  • Also, the MCP SDK assumes its users are developers writing their own plugin scripts. The @rushstack/mcp-server should have a different goal, to provide a premade configure that "just works" for each monorepo, with minimal setup/understanding required by end users.

The draft PR microsoft/rush-example#24 illustrates a configuration.

TODO:

• Agree on the design
• Implement the plugin loader
• Convert existing MCP tools to use this model
• Extract the rush_docs plugin into a build-tests example

[octogonz]

@L-Qun completed this with #5241