Teams guide

This MCP server provides a clean-code guidance document, can read external project files for analysis, and suggests improvements based on established guidelines. It helps you quickly access a structured guide, inspect code, and receive actionable feedback.

How to use

You will use an MCP client to interact with the guide server. Read the clean-code guidance, pull in files from external projects for analysis, and run checks that compare code against the guide to surface improvement opportunities.

How to install

Prerequisites: ensure you have Node.js version 20.18.0 or higher and npm installed on your system.

Install and configure the MCP client with the following steps.

// 1) Verify Node.js and npm versions
node -v
npm -v

// 2) Configure your MCP client to connect to the guide server
{
  "mcpServers": {
    "guide-mcp": {
      "command": "npx",
      "args": ["-y", "teams-guide-mcp"]
    }
  }
}

Additional setup and usage notes

After configuring the MCP client, restart the client to apply changes. You can access guide documents from the MCP client using the guide URL scheme guide://, for example guide://clean-code-guide.md. Use this to read the guided material directly within the client.

Common tasks you can perform with the MCP client include reading a guide, reading a file from an external project, and checking code against the guide to surface improvement suggestions. Use the tools in the client as described in practical scenarios such as reading the guide, reading a file, and running a clean-code check.

Notes on usage scenarios

Scenario: Read the clean-code guide to learn naming conventions and general guidelines.

Scenario: Read an external file to inspect a utility module and understand how it relates to the guide recommendations.

Scenario: Check a file against the clean-code guide to receive suggested improvements and align your code with best practices.

Project structure

A typical layout includes a guides directory with markdown guidance documents and a src directory containing code to analyze. The MCP server main code runs from the src/index.js file, and guide documents live under guides/.md files.

Developer notes

To add new guide documents, place .md or .txt files in guides/ and they will be recognized automatically. You can perform automatic builds and deployments via the project’s CI workflow to ensure the MCP server and guides stay up to date.

Troubleshooting

If the MCP client does not seem to connect, verify your mcpServers configuration is loaded by the client and that the command and arguments match the example. Ensure you restarted the client after making changes.

Resources and access

You can access guide documents directly through the client using guide://<filename>, such as guide://clean-code-guide.md, to read the content without leaving the client environment.

Available tools

get_guide

Reads and returns the content of a specified guide file from the guides directory, such as clean-code-guide.md.

read_file

Reads and returns the contents of a file from an external project given a path.

check_clean_code

Analyzes a target file against the clean-code guide and provides improvement suggestions based on the guide's rules.