TobiSan5/first-mcp

First MCP Server

A comprehensive MCP server for Claude Desktop and other MCP clients, featuring memory management, workspace file I/O, weather data, and utility tools.

🚀 What's New in v1.1.0

Interface Simplified: Reduced from 52 to 32 tools (38% fewer options) while preserving all essential functionality.

Key improvements:

• ✅ Streamlined tool set focusing on core functionality
• ✅ Enhanced architecture with proper delegation patterns
• ✅ Improved testing infrastructure
• ✅ Better developer experience with cleaner codebase

🎯 For End Users

Quick Installation

# Install directly from GitHub (recommended)
pip install git+https://github.com/TobiSan5/first-mcp.git

# Or clone and install locally
git clone https://github.com/TobiSan5/first-mcp.git && cd first-mcp && pip install -e .

Essential Setup

1. Set environment variables (create directories for your data):

   # Windows
   setx FIRST_MCP_DATA_PATH "%APPDATA%\FirstMCP"
   setx FIRST_MCP_WORKSPACE_PATH "%USERPROFILE%\Documents\ClaudeWorkspace"
   
   # macOS/Linux  
   export FIRST_MCP_DATA_PATH="$HOME/.local/share/FirstMCP"
   export FIRST_MCP_WORKSPACE_PATH="$HOME/Documents/ClaudeWorkspace"
   

2. Configure your MCP client (Claude Desktop example):

   {
     "mcpServers": {
       "first-mcp": {
         "command": "first-mcp",
         "env": {
           "FIRST_MCP_DATA_PATH": "/path/to/your/data",
           "FIRST_MCP_WORKSPACE_PATH": "/path/to/your/workspace"
         }
       }
     }
   }
   

3. Restart your MCP client and start using the tools!

What You Get

Core Tools (32 total):

• Memory Management: Store, search, and organize information across sessions
• File Workspace: Persistent file storage with tagging and metadata
• Weather Data: Location lookup and weather forecasts
• Calculator: Secure math expressions and time differences
• Database Operations: Generic TinyDB database management
• System Utilities: File listing, text analysis, calendar, system info

Try these commands in Claude:

• "Store this important info: [your note]"
• "Search my memories for python projects"
• "What tools do you have available?"
• "Get weather for Oslo, Norway"
• "Calculate: 2^10 + 24"
• "Store this code snippet in a file"

🛠️ For Developers and Adapters

Architecture Overview

The package follows a clean 3-layer architecture:

MCP Layer (server_impl.py)
├─ Tool registration and MCP protocol handling  
├─ Server timestamps and error formatting
└─ Parameter validation

Server Logic Layer
├─ Business rules and validation
├─ Response formatting  
└─ Environment configuration

Data Processing Layer (memory/, fileio/, etc.)  
├─ Pure data manipulation functions
├─ Database operations
└─ External API integrations

Key Features for Integration

• Modular Design: Memory system extracted as reusable package (src/first_mcp/memory/)
• Clean Imports: All components available via explicit imports
• Environment-Based Config: Uses environment variables for all paths and API keys
• Comprehensive Testing: 3-tier test structure (MCP protocol, data layer, intelligence layer)
• Backward Compatible: Safe to upgrade from previous versions

Development Setup

# Clone and set up development environment
git clone https://github.com/TobiSan5/first-mcp.git
cd first-mcp
pip install -e .

# Run tests
python tests/server_implementation/test_mcp_client.py

# Run in debug mode
python -m first_mcp.server --debug

Adding New Tools

Simply add functions with @mcp.tool() decorator to src/first_mcp/server_impl.py:

@mcp.tool()
def my_custom_tool(input_text: str) -> Dict[str, Any]:
    """
    Your tool description here.
    
    Args:
        input_text: Description of parameter
        
    Returns:
        Dictionary with results
    """
    result = {"processed": input_text.upper()}
    return add_server_timestamp(result)  # Include server timestamp

📚 Documentation

• - Interface changes and improvements
• - Development roadmap and version info
• - Architecture and implementation details
• - 3-tier test structure and examples

🌐 MCP Ecosystem

This server works with any Model Context Protocol (MCP) compatible application:

• Claude Desktop - Primary target
• Cursor - IDE integration
• VS Code with MCP extension - Development environment
• Any MCP client - Protocol-compliant applications

🔧 Environment Variables (Optional)

# API Keys (for weather functionality)
export OPENWEATHERMAPORG_API_KEY="your_key_here"  
export GOOGLE_API_KEY="your_key_here"

# Data Storage (defaults to current directory if not set)
export FIRST_MCP_DATA_PATH="/custom/data/path"
export FIRST_MCP_WORKSPACE_PATH="/custom/workspace/path" 

🐛 Troubleshooting

Common issues:

1. "Tools not found" → Verify MCP client configuration and restart the client
2. "Import error" → Ensure package installed in correct Python environment
3. "Permission denied" → Check that data/workspace directories exist and are writable
4. "No such file" → Run first-mcp --debug to check setup

Debug mode:

python -m first_mcp.server --debug

📈 Version History

• v1.1.0 (2025-09-05): Interface optimization - reduced 52→32 tools, architecture improvements
• v1.0.0: Initial release with full feature set

License: MIT | Author: Torbjørn Wikestad | Repo: github.com/TobiSan5/first-mcp