MCP Server (mcp-tools)

This project contains a general MCP server designed to provide tools for AI agents, communicating via stdin/stdout using the Model Context Protocol (MCP).

Tools Provided

The server currently offers the following tools, callable via the call_tool endpoint:

check_markdown_link_file

• Description: Checks HTTP/HTTPS links in a single specified Markdown file.
• Arguments:
  • file_path (string, required): The path to the Markdown file (relative to the project root or absolute).
• Example arguments:

  {
    "file_path": "docs/usage.md"
  }
  

• Output: A text report detailing the status of links found in the file (total, valid, broken, errors).

check_markdown_link_files

• Description: Checks HTTP/HTTPS links within a provided list of Markdown files.
• Arguments:
  • file_paths (list of strings, required): A list of paths to the Markdown files (relative to the project root or absolute).
• Example arguments:

  {
    "file_paths": [
      "README.md",
      "docs/requirements/link_checker_tool_enhancements_reqs.md"
    ]
  }
  

• Output: A consolidated text report summarizing the link status across all processed files.

check_markdown_link_directory

• Description: Recursively scans a specified directory for *.md files and checks HTTP/HTTPS links within them.
• Arguments:
  • directory_path (string, required): The path to the directory to scan.
• Example arguments:

  {
    "directory_path": "docs/"
  }
  

• Output: A consolidated text report summarizing the link status across all Markdown files found in the directory.

check_markdown_links_project

• Description: Scans the entire project for *.md files, excluding those listed in the root .gitignore file, and checks HTTP/HTTPS links within the remaining files.
• Arguments: None.
• Example arguments:

  {}
  

• Output: A consolidated text report summarizing the link status across all processed Markdown files found in the project (respecting .gitignore).

Setup & Usage (Using Makefile)

This project uses uv for environment and dependency management, orchestrated via a Makefile.

1. Navigate to the project directory: Ensure you are in the root directory of this project (mcp-server).

   cd /path/to/mcp-server
   

2. Install dependencies (including dev/test): This command creates a local virtual environment (.venv) if it doesn't exist and installs all necessary packages using uv.

   make install-dev
   

3. Run Tests & Coverage:

   make test
   

   This command runs all unit tests using pytest and generates a code coverage report using coverage.py.

   • The test run is configured to fail if the total coverage drops below 85% (see Makefile).
   • As of 2025-04-04, the coverage status is:
     • Overall: 85%
     • src/mcp_server/server.py: 81% (Main handlers covered; main loop untested)
     • src/mcp_server/tools/link_checker.py: 89% (Core logic covered; some edge cases in status checking untested)

4. Lint & Format Code: Uses ruff to check for linting errors and format the code according to project standards.

   make lint
   

5. Run the Server (Manually): The server listens on stdin/stdout.

   make run
   

   (Note: Manual interaction requires sending correctly framed JSON-RPC messages, including initialize and initialized before call_tool.)

6. Clean Up: Removes the virtual environment and cache files.

   make clean
   

Cursor MCP Integration (Linux)

This server can be integrated with Cursor as an MCP tool using the following global configuration in ~/.cursor/mcp.json (you may need to create this file/directory):

{
  "mcpServers": {
    "local-link-checker": {
      "name": "Local Link Checker", // Name displayed in Cursor
      "type": "command",
      // Use the absolute path to the python executable within THIS project's venv
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": [
        "-m", // Run module
        "mcp_server.server" // The server module to run
      ]
      // Optional: Define the working directory if needed (usually handled by -m)
      // "cwd": "/absolute/path/to/mcp-server"
    }
  }
}

Important Notes for Integration:

• Absolute Paths: You MUST replace /absolute/path/to/mcp-server with the correct, absolute path to this project's directory on your system.
• Virtual Environment: This configuration assumes you have run make install-dev first to create the .venv and install dependencies within this project directory.
• Working Directory & File Paths: When run via python -m, the server's working directory is typically the project root (/absolute/path/to/mcp-server). Therefore, when invoking the tool (e.g., @Local Link Checker), the file_path argument should be relative to this project root (e.g., file_path: test_links.md for a file at the root) or an absolute path.
• Restart Cursor: After adding or modifying ~/.cursor/mcp.json, you must restart Cursor for the changes to take effect.

Previous integration attempts using different methods (like uv run or shell wrappers) failed due to issues with Cursor's process execution environment on Linux. The direct python -m approach using the project's own virtual environment is the configuration proven to work.

Adding New Tools

1. Define the tool's schema in handle_list_tools (src/mcp_server/server.py).
2. Implement the tool's logic under a new elif name == "your-tool-name": block in handle_call_tool (src/mcp_server/server.py).
   • Create helper functions in separate files under src/mcp_server/tools/ as needed.
   • Add unit tests for the helper functions in tests/.
3. Add any new dependencies to pyproject.toml.
4. Update the install-dev target in the Makefile if new test-only dependencies are added (base dependencies should be handled by uv sync within install-dev).
5. Update this README.

Contributing

Contributions are welcome! Please follow standard coding practices and ensure tests pass (make test) before submitting pull requests.

License

[Specify your license here]