BlackArch Security Tools MCP Server

A comprehensive Model Context Protocol (MCP) server that integrates BlackArch Linux security tools for educational penetration testing. Built with security-first principles and strict input validation.

What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI assistants to external data sources and tools. This project serves as a starting point for building your own MCP servers.

Features

Echo Tool: A simple tool that echoes back any message you send
Echo Resource: A resource that can be read with custom messages
FastMCP Framework: Built using the modern FastMCP library
Comprehensive Testing: Includes PowerShell and Bash test scripts
Easy Setup: Minimal dependencies and clear structure

Quick Start

Prerequisites

Python 3.13 or higher
jq (for JSON formatting in tests)

Installation

Clone or download this project
Install dependencies:
pip install -r requirements.txt
or using uv (recommended):
uv sync

Running the Server

python echo_server.py

The server runs in stdio mode, waiting for JSON-RPC requests.

Testing the Server

Quick Test with jq

# Test tool listing echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | python echo_server.py echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' | python echo_server.py echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python echo_server.py | jq

Comprehensive Testing

PowerShell (Windows):

& "C:\Program Files\PowerShell\7-preview\pwsh.exe" -File test_echo_mcp.ps1

Bash (Linux/macOS):

chmod +x test_echo_mcp.sh ./test_echo_mcp.sh

Project Structure

project-011/ ├── echo_server.py # Main MCP server implementation ├── test_echo_mcp.ps1 # Comprehensive PowerShell test script ├── test_echo_mcp.sh # Bash test script ├── requirements.txt # Python dependencies ├── pyproject.toml # Project configuration └── README.md # This file

Understanding the Code

Basic MCP Server Structure

from mcp.server.fastmcp import FastMCP # Create the MCP server mcp = FastMCP("YourServerName") # Define a tool @mcp.tool() def your_tool(param: str) -> str: """Description of what your tool does""" return f"Result: {param}" # Define a resource @mcp.resource("your://{param}") def your_resource(param: str) -> str: """Description of your resource""" return f"Resource content: {param}" # Run the server if __name__ == "__main__": mcp.run(transport='stdio')

Key Concepts

Tools: Functions that can be called by AI assistants to perform actions
Resources: Data sources that can be read by AI assistants
Transport: How the server communicates (stdio, HTTP, etc.)
JSON-RPC: The protocol used for communication

Creating Your Own MCP Server

1. Start with the Echo Server

Copy this project and modify echo_server.py:

from mcp.server.fastmcp import FastMCP mcp = FastMCP("MyCustomServer") @mcp.tool() def my_custom_tool(input_data: str) -> str: """My custom tool that does something useful""" # Your logic here return f"Processed: {input_data}" if __name__ == "__main__": mcp.run(transport='stdio')

2. Add More Complex Tools

from typing import List, Dict, Any import requests @mcp.tool() def fetch_weather(city: str) -> Dict[str, Any]: """Fetch weather data for a city""" # Your API call logic here return {"city": city, "temperature": "22°C", "condition": "sunny"} @mcp.tool() def process_data(data: List[str]) -> List[str]: """Process a list of data items""" return [item.upper() for item in data]

3. Add Resources

@mcp.resource("data://{dataset}") def get_dataset(dataset: str) -> str: """Get data from a specific dataset""" # Your data retrieval logic here return f"Data from {dataset}: ..."

4. Update Dependencies

Add any new dependencies to requirements.txt:

mcp[cli]>=1.15.0 requests>=2.31.0 pandas>=2.0.0

Integration with AI Assistants

Claude Desktop

Add to your claude_desktop_config.json:

{ "mcpServers": { "echo-server": { "command": "python", "args": ["C:/path/to/your/echo_server.py"] } } }

Other MCP Clients

The server follows the MCP specification and should work with any MCP-compatible client.

Testing Your Server

Manual Testing

Initialize the server:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}
Send initialized notification:
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
List available tools:
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
Call a tool:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo_tool","arguments":{"message":"Hello!"}}}

Automated Testing

Use the provided test scripts as templates for your own testing:

test_echo_mcp.ps1 - Comprehensive PowerShell testing
test_echo_mcp.sh - Bash testing

Common Issues and Solutions

"Failed to validate request: Received request before initialization was complete"

Solution: Always send the initialization sequence first:

initialize request
notifications/initialized
Then your actual requests

"Tool not found" errors

Solution: Check that your tool is properly decorated with @mcp.tool() and the name matches exactly.

Performance issues

Solution:

Use async functions for I/O operations
Implement proper error handling
Consider caching for expensive operations

Next Steps

Explore the MCP Specification: Official MCP Documentation
Check out FastMCP: FastMCP GitHub
Build Real Tools: Create tools that interact with APIs, databases, or file systems
Add Authentication: Implement security for production use
Deploy: Consider containerization with Docker

Contributing

This is a template project. Feel free to:

Fork and modify for your needs
Add more examples
Improve the test scripts
Share your MCP server implementations

License

This project is provided as-is for educational and development purposes.

Happy MCP Development! 🚀

For questions or issues, refer to the MCP Community or create an issue in your fork of this project.

Echo MCP Server