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

1. Clone or download this project
2. 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

1. Initialize the server:

   {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}
   

2. Send initialized notification:

   {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
   

3. List available tools:

   {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
   

4. 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:

1. initialize request
2. notifications/initialized
3. 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

1. Explore the MCP Specification: Official MCP Documentation
2. Check out FastMCP: FastMCP GitHub
3. Build Real Tools: Create tools that interact with APIs, databases, or file systems
4. Add Authentication: Implement security for production use
5. 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.