bw00786/wilk_mcp_server

Python MCP Server A full-featured Model Context Protocol (MCP) server implementation in Python, providing tools for note-taking, task management, calculations, and system monitoring. Features 🛠️ Tools

Note Management: Create, list, and retrieve notes Task Management: Create, list, and update tasks with priorities and due dates Calculator: Perform mathematical calculations System Information: Get real-time system metrics

📚 Resources

Notes Database: Access to SQLite database containing all notes Tasks Database: Access to SQLite database containing all tasks Server Log: Access to server activity logs

💬 Prompts

Daily Summary: Generate comprehensive daily summaries Task Reminders: Create reminders for upcoming tasks

Installation Prerequisites

Python 3.7+ pip package manager

Quick Setup

Clone or download the files: bash# Create a new directory mkdir mcp-server cd mcp-server

Save the Python files (mcp_server.py, test_client.py)

Save requirements.txt and setup.sh

Run the setup script: bashchmod +x setup.sh ./setup.sh

Activate the virtual environment: bashsource venv/bin/activate

Manual Setup bash# Create virtual environment python3 -m venv venv source venv/bin/activate

Install dependencies

pip install psutil

Make scripts executable

chmod +x mcp_server.py chmod +x test_client.py Usage Starting the Server The MCP server communicates via JSON-RPC over stdin/stdout: bashpython mcp_server.py The server will wait for JSON-RPC requests on stdin and respond on stdout. Testing with the Demo Client Full Demo Run a comprehensive demo that tests all server features: bashpython test_client.py Interactive Mode Use the interactive client for manual testing: bashpython test_client.py interactive Available interactive commands:

create_note

Example interactive session: mcp> create_note "Meeting Notes" "Discussed project timeline and deliverables" ✅ Note created successfully

mcp> create_task "Review Code" "Review pull request #123" 2 "2025-07-01" ✅ Task created successfully

mcp> list_tasks 1: Review Code - pending (Priority: 2)

mcp> calculate 2 + 2 * 3 = 8

mcp> quit API Reference Tools create_note Create a new note with title and content. json{ "name": "create_note", "arguments": { "title": "Note Title", "content": "Note content here" } } list_notes List all notes with basic information. json{ "name": "list_notes", "arguments": {} } get_note Retrieve a specific note by ID. json{ "name": "get_note", "arguments": { "note_id": 1 } } create_task Create a new task with optional metadata. json{ "name": "create_task", "arguments": { "title": "Task Title", "description": "Optional description", "priority": 3, "due_date": "2025-07-01" } } list_tasks List tasks with optional status filtering. json{ "name": "list_tasks", "arguments": { "status": "pending" // Optional: "pending", "completed", "cancelled" } } update_task_status Update the status of an existing task. json{ "name": "update_task_status", "arguments": { "task_id": 1, "status": "completed" } } calculate Perform mathematical calculations. json{ "name": "calculate", "arguments": { "expression": "2 + 2 * 3" } } get_system_info Retrieve current system information. json{ "name": "get_system_info", "arguments": {} } Resources sqlite://notes Access the notes database directly. sqlite://tasks Access the tasks database directly. file://server.log Access server activity logs. Prompts daily_summary Generate a comprehensive daily summary. json{ "name": "daily_summary", "arguments": { "date": "2025-06-23" // Optional, defaults to today } } task_reminder Generate reminders for upcoming tasks. json{ "name": "task_reminder", "arguments": { "days_ahead": 7 // Optional, defaults to 7 days } } JSON-RPC Protocol Examples Initialize Connection json{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "My Client",
"version": "1.0.0" } } } List Available Tools json{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" } Call a Tool json{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "create_note", "arguments": { "title": "My Note", "content": "This is my note content" } } } Read a Resource json{ "jsonrpc": "2.0", "id": 4, "method": "resources/read", "params": { "uri": "sqlite://notes" } } Data Storage The server uses SQLite databases stored in the system's temporary directory:

Notes: id, title, content, created_at, updated_at Tasks: id, title, description, status, priority, created_at, due_date

Database location: {temp_dir}/mcp_server.db Security Considerations

The calculator tool uses eval() with character filtering for basic security Only allows basic mathematical operations: 0-9, +, -, *, /, (, ), ., and spaces Database uses parameterized queries to prevent SQL injection No network access or file system operations beyond the temporary database

Error Handling The server provides detailed error responses following JSON-RPC standards:

-32700: Parse error (invalid JSON) -32601: Method not found -32602: Invalid params -32603: Internal error

Extending the Server Adding New Tools

Define the tool in register_tools():

pythonself.tools["my_tool"] = Tool( name="my_tool", description="Description of what the tool does", inputSchema={ "type": "object", "properties": { "param1": {"type": "string", "description": "Parameter description"} }, "required": ["param1"] } )

Implement the tool logic in execute_tool():

pythonelif tool_name == "my_tool": return await self.my_tool_implementation(arguments["param1"])

Create the implementation method:

pythonasync def my_tool_implementation(self, param1: str) -> Dict[str, Any]: # Your tool logic here return {"result": "Tool executed successfully"} Adding New Resources Follow the same pattern in register_resources() and handle_read_resource(). Adding New Prompts Follow the same pattern in register_prompts() and generate_prompt(). Troubleshooting Common Issues

Import Error for psutil: Run pip install psutil Permission Denied: Make sure scripts are executable with chmod +x Database Locked: Close any other processes using the database JSON Parse Errors: Ensure requests are properly formatted JSON-RPC

Debug Mode Enable detailed logging by setting the log level: pythonlogging.basicConfig(level=logging.DEBUG) Testing Individual Components You can test individual tools using the interactive client or by sending manual JSON-RPC requests. Contributing Feel free to extend this MCP server implementation with additional tools, resources, or prompts. The modular design makes it easy to add new functionality. License This implementation is provided as-is for educational and development purposes.