Mcp Discovery

What is Mcp Discovery about?

Mcp Discovery inspects an MCP Server and produces a structured report of its tools, resources, and capabilities. The tool can render the report directly in the console or write it to files in several formats, making it easy to keep documentation up‑to‑date.

How to use Mcp Discovery?

1. Run the CLI – the default subcommand print shows capabilities in the terminal.

   mcp-discovery -- npx -y @modelcontextprotocol/server-everything
   

2. Create a file – use the create subcommand with -f to specify the output file and optionally choose a built‑in template (md, md-plain, html, txt).

   mcp-discovery create -f capabilities.md -- npx -y @modelcontextprotocol/server-everything
   

3. Update an existing file – use update and place marker comments (mcp-discovery-render / mcp-discovery-render-end) in the target file. The command inserts the generated content between those markers.

   mcp-discovery update -f README.md -- npx -y @modelcontextprotocol/server-everything
   

4. Custom templates – supply a Handlebars file with --template-file or an inline template string with --template-string.
5. GitHub Action – the project can be run as a GitHub Action to automatically refresh documentation during CI.

Key Features

• Terminal display of MCP Server details.
• Generation of Markdown, HTML, plain‑text, or JSON files.
• In‑place file updates using marker annotations.
• Built‑in templates (md, md-plain, html, txt).
• Support for custom Handlebars templates via file or inline string.
• Ready‑to‑use GitHub Action for CI automation.
• Automatic template selection based on file extension when none is specified.

Use Cases

• Documentation automation – keep README or wiki pages synchronized with the latest server capabilities.
• CI/CD pipelines – generate capability reports as artifacts or embed them in release notes.
• Developer onboarding – provide a quick CLI view of server features for new team members.
• Custom reporting – tailor output with Handlebars templates for internal dashboards or external publications.

FAQ

Q: Do I need to install Rust to use the tool? A: No. Pre‑built binaries are provided for major platforms; you can also install via cargo install mcp-discovery if Rust is available.

Q: How do I choose the output format? A: Use -t/--template with one of the built‑in names (md, md-plain, html, txt) or supply your own template via --template-file or --template-string.

Q: What if I omit a subcommand? A: print is the default, so the tool will display capabilities in the terminal.

Q: Can I run Mcp Discovery inside a GitHub Action? A: Yes. Follow the instructions in the mcp-discovery-action repository to add the step to your workflow.

Q: How are update markers defined? A: Insert <!-- mcp-discovery-render --> and <!-- mcp-discovery-render-end --> for Markdown/HTML, or the language‑appropriate comment syntax for other file types. Optional inline template blocks can be added between <!-- mcp-discovery-template --> and <!-- mcp-discovery-template-end -->.

MCP Discovery

A command-line tool written in Rust for discovering and documenting MCP Server capabilities.

It supports outputting the results in the terminal or saving them to files in Markdown, HTML, plain text, JSON, or a custom template defined by you.

Check the project documentation for instructions and command examples.

Features 💡

• Display MCP Details: Output MCP Server information, including tools, resources, and capabilities, directly to the terminal.
• Generate Files: Create files in Markdown (.md), HTML (.html), or plain text (.txt) formats with MCP Server details and capabilities.
• Update Files: Modify existing Markdown, HTML, or text files by adding MCP Server capabilities within specified markers, enabling MCP Server developers to automatically maintain up-to-date documentation and repository README files.
• Flexible Output Customization: Choose from built-in templates (md, md-plain, html, txt) or supply custom Handlebars templates for personalized output.
• MCP Discovery GitHub Action: Integrate the mcp-discovery CLI as a GitHub Action to automate and maintain up-to-date MCP Server documentation in your development workflow.

This open-source project leverages the rust-mcp-sdk for seamless interaction with MCP Servers.

🌐 Check out the rust-mcp-filesystem capabilities page for a sample output.

Installation ⬇️

Running as CLI

Check the project documentation for instructions on installing the tool on different platforms.

GitHub Action

The easiest way to automate and maintain up-to-date MCP Server documentation , is to use mcp-discovery as a GitHub action. Please see rust-mcp-stack/mcp-discovery-action for installation and configuration instructions.

Subcommands

• print: Displays MCP Server capabilities in the terminal.
• create: Creates a new file with MCP Server capability details.
• update: Updates an existing file by inserting MCP Server capabilities between specified markers.

👉 Note: If no subcommand is provided, the print subcommand will be used by default.

Options ⚙️

• -f, --filename <FILENAME>: Used with create and update commands to specify the output file to generate or modify.
• -t, --template <TEMPLATE>: Choose a built-in output template. Options: md, md-plain, html, txt.
• -p, --template-file <TEMPLATE_FILE>: Path to a custom Handlebars template file.
• -s, --template-string <TEMPLATE_STRING>: Inline Handlebars template provided as a string.
• -h, --help: Display help information.
• -V, --version: Display the version of mcp-discovery.

👉 Note: If no template is provided, mcp-discovery will automatically select the most suitable built-in template based on the file extension.

Built-in Templates 🧬

The CLI supports the following built-in output templates:

• md: Formatted Markdown that presents MCP Server capabilities in a table format.
• md-plain: Minimalist Markdown for straightforward output, using plain text instead of tables.
• html: Structured HTML with basic styling.
• txt: Plain text for raw, unformatted output.

Custom Templates 🧩

You can provide custom Handlebars templates in different ways:

1. Use the --template-file flag to provide a custom template file.
2. Use the --template-string flag to provide a raw Handlebars template directly as a string.
3. To use an inline template, define it in a file for the update command only — this will not function with print or create.

Inline templates must be enclosed within designated marker annotations.

Examples

Print MCP Server capabilities to the terminal:

mcp-discovery -- npx -y @modelcontextprotocol/server-everything

Create a HTML file with MCP Server capabilities:

mcp-discovery create -f capabilities.html -- npx -y @modelcontextprotocol/server-everything

📄 Click here to view generated html file

Create a MD file with MCP Server capabilities:

mcp-discovery create -f capabilities.md -- npx -y @modelcontextprotocol/server-everything

Use a custom Handlebars template:

mcp-discovery create -f capabilities.md  --template-file=custom_template.hbs -- npx -y @modelcontextprotocol/server-everything

💡 See the Command Examples section in the project documentation for additional CLI usage examples.

Defining Update Regions with Markers

When using the update subcommand, mcp-discovery places capabilities between designated markers in the target file, which vary by file format and are typically comment lines. The update command simplifies the process for developers and maintainers to keep documentation current effortlessly. Run the mcp-discovery update command anytime to refresh the file with the latest MCP Server capabilities.

Marker Annotations

• Render Block Start : mcp-discovery-render
• Render Block End : mcp-discovery-render-end

👉 The mcp-discovery-render marker supports template and template-file properties as well. Check the examples below for details.

You can optionally include an inline template identifier within the render block, enclosed by:

• Template Block Start: mcp-discovery-template
• Template Block End: mcp-discovery-template-end

If a template annotation is detected within a render block, mcp-discovery will use it to render the output. This allows for customized templates without depending on built-in or external template files. Check the examples below for details:

Sample Markdown file annotated with render block:

# Server Info and Capabilities

<!-- mcp-discovery-render -->

Server Capabilities will be placed here...

<!-- mcp-discovery-render-end -->

Sample Markdown file, annotated with render block and template name:

# Server Info and Capabilities

<!-- mcp-discovery-render template=md-plain -->

Server Capabilities will be placed here...

<!-- mcp-discovery-render-end -->

Sample Markdown file, annotated with render block and custom template file:

# Server Info and Capabilities

<!-- mcp-discovery-render template=my-custom-template.hbs -->

Server Capabilities will be placed here...

<!-- mcp-discovery-render-end -->

Sample HTML file with annotations :

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My MCP Server</title>
  </head>
  <body>
    <h1>MCP Server Details</h1>
    <div>
      <!-- mcp-discovery-render -->

      <!-- mcp-discovery-render-end -->
    </div>
  </body>
</html>

Sample HTML file with inline template :

<h1>MCP Server Details</h1>
<div>
  <!-- mcp-discovery-render -->
  <!-- mcp-discovery-template
    <b>Name: </b>{{name}}
    <br/>
    <b>Version: </b>{{version}}
    <br/>
    <b>Number of tools:</b> {{len tools}}
    <h2>Summary:</h2>
    {{> html-summary }}
    mcp-discovery-template-end -->
  <!-- mcp-discovery-render-end -->
</div>

Below is a screenshot showing the resulting HTML after the mcp-discovery update command is executed:

You can execute the mcp-discovery update command whenever you need to refresh the file with the latest MCP Server capabilities.

Contributing

We welcome everyone who wishes to contribute! Please refer to the contributing guidelines for more details.

All contributions, including issues and pull requests, must follow Rust's Code of Conduct.

Unless explicitly stated otherwise, any contribution you submit for inclusion in mcp-discovery is provided under the terms of the MIT License, without any additional conditions or restrictions.

License

This project is licensed under the MIT License. see the LICENSE file for details.