https://github.com/danfmaia/mcp-server
https://github.com/danfmaia/mcp-server
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/danfmaia/mcp-server
- Owner: danfmaia
- Created: 2025-04-05T07:18:38.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-05T07:19:27.000Z (6 months ago)
- Last Synced: 2025-04-05T08:23:48.507Z (6 months ago)
- Language: Python
- Size: 125 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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`:**
```json
{
"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`:**
```json
{
"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`:**
```json
{
"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`:**
```json
{}
```
- **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`).
```bash
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`.
```bash
make install-dev
```
3. **Run Tests & Coverage:**
```bash
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.
```bash
make lint
```
5. **Run the Server (Manually):**
The server listens on stdin/stdout.
```bash
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.
```bash
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):
```json
{
"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]