MCP.vx

shahinvx/MCP.vx

3.2

If you are the rightful owner of MCP.vx and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Model Context Protocol (MCP) is a framework that enables AI models to interact with external tools, data sources, and services, enhancing their capabilities and interoperability.

Tools
2
Resources
0
Prompts
0

šŸš€ MCP Project Getting Started Guide

A comprehensive guide to creating and managing MCP (Model Context Protocol) server projects using the create_mcp_project.py boilerplate generator.

šŸ“‹ Table of Contents

šŸ¤– What is MCP?

Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools, data sources, and services. Think of it as a bridge that allows AI assistants to:

  • šŸ”§ Execute functions (tools) - Perform calculations, API calls, file operations
  • šŸ“Š Access information (resources) - Read documentation, fetch data, provide context
  • šŸ’¬ Use templates (prompts) - Standardized conversation patterns and responses

Why Use MCP?

  • Standardized: Works with multiple AI platforms (Claude, ChatGPT, etc.)
  • Modular: Easy to add, remove, or modify capabilities
  • Scalable: From simple calculators to complex business systems
  • Interoperable: Share tools across different applications

šŸš€ Quick Start

Prerequisites

  • Python 3.8+ installed
  • Node.js (for MCP Inspector testing)
  • Basic understanding of Python

Step 1: Create Your First MCP Project

# Download the project creator
python create_mcp_project.py my_first_mcp_server

# Navigate to your project
cd my_first_mcp_server

# Set up the project (installs dependencies and runs tests)
# Windows:
setup.bat

# Linux/Mac:
./setup.sh

Step 2: Start Your MCP Server

python src/server/app.py

You'll see output like:

Starting My First Mcp Server MCP Server on localhost:8001
Calculator Tools: add, subtract
Resources: calculator/help, calculator/operations
Prompts: welcome, help, error

Step 3: Test with MCP Inspector

Open a new terminal and run:

npx @modelcontextprotocol/inspector@latest http://localhost:8001/mcp

This opens a web interface where you can test your MCP server interactively!

šŸ“ Project Structure

The create_mcp_project.py script generates a well-organized project structure:

my_first_mcp_server/
ā”œā”€ā”€ šŸ“‹ fastmcp.json                    # MCP server configuration
ā”œā”€ā”€ šŸ“¦ requirements.txt                # Python dependencies
ā”œā”€ā”€ šŸ”§ setup.bat / setup.sh            # Platform-specific setup scripts
ā”œā”€ā”€ šŸŒ .env.example                    # Environment variables template
ā”œā”€ā”€ šŸ“– README.md                       # Project documentation
ā”œā”€ā”€ šŸš« .gitignore                      # Git ignore rules
ā””ā”€ā”€ šŸ“‚ src/
    ā”œā”€ā”€ šŸ“‚ server/
    ā”‚   ā”œā”€ā”€ šŸš€ app.py                   # Main MCP server entry point
    ā”‚   ā”œā”€ā”€ šŸ“‚ tools/                   # šŸ”§ TOOLS: Actions that DO things
    ā”‚   ā”‚   ā””ā”€ā”€ calculator_tools.py     # Basic arithmetic operations
    ā”‚   ā”œā”€ā”€ šŸ“‚ resources/               # šŸ“Š RESOURCES: Information providers
    ā”‚   ā”‚   ā””ā”€ā”€ calculator_resource.py  # Help info & operation lists
    ā”‚   ā””ā”€ā”€ šŸ“‚ prompts/                 # šŸ’¬ PROMPTS: Conversation templates
    ā”‚       ā””ā”€ā”€ calculator_prompts.py   # Welcome, help & error messages
    ā””ā”€ā”€ šŸ“‚ tests/
        ā””ā”€ā”€ test_calculator.py          # Simple unit tests

šŸ§© Understanding MCP Components

šŸ”§ Tools - "The Doers"

Tools are functions that perform actions. They're like API endpoints that AI models can call.

Example: Calculator Tools

@calculator_mcp.tool
def add(a: float, b: float) -> float:
    """Add two numbers together."""
    result = a + b
    print(f"Adding {a} + {b} = {result}")
    return result

When to use Tools:

  • Mathematical calculations
  • API calls to external services
  • File operations
  • Database queries
  • System commands

šŸ“Š Resources - "The Informers"

Resources provide information and context to AI models. They're like reference materials.

Example: Help Documentation

@calculator_resources.resource("file://calculator/help")
def calculator_help():
    """Provides comprehensive help information."""
    return {
        "type": "text",
        "content": "Calculator Help\n\nAvailable Operations:\n- add(a, b)\n- subtract(a, b)"
    }

When to use Resources:

  • Documentation and help text
  • Configuration data
  • Static datasets
  • API schemas
  • Knowledge bases

šŸ’¬ Prompts - "The Communicators"

Prompts are conversation templates that provide consistent, user-friendly interactions.

Example: Welcome Message

@calculator_prompts.prompt("welcome")
def welcome_prompt(user_name: str = "User"):
    """Generate a friendly welcome message."""
    return f"Hello {user_name}! Welcome to the Calculator MCP Server."

When to use Prompts:

  • User onboarding
  • Help messages
  • Error explanations
  • Conversation starters
  • Status updates

šŸ’” Examples

Example 1: Basic Calculator (Generated by Default)

python create_mcp_project.py calculator_server
cd calculator_server
python src/server/app.py

Available Tools:

  • add(5, 3) ā†’ Returns 8
  • subtract(10, 4) ā†’ Returns 6

Example 2: Weather Service MCP

python create_mcp_project.py weather_server
cd weather_server

Then modify src/server/tools/calculator_tools.py to add weather tools:

@calculator_mcp.tool
def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    # Mock implementation
    return {
        "city": city,
        "temperature": "22Ā°C",
        "condition": "Sunny",
        "humidity": "45%"
    }

Example 3: File Manager MCP

python create_mcp_project.py file_manager
cd file_manager

Add file operations:

@calculator_mcp.tool
def list_files(directory: str = ".") -> list:
    """List files in a directory."""
    import os
    return os.listdir(directory)

@calculator_mcp.tool
def read_file(file_path: str) -> str:
    """Read content of a text file."""
    with open(file_path, 'r') as f:
        return f.read()

šŸ”§ Advanced Usage

Adding Multiple Tool Modules

  1. Create a new tool module:
# In your project directory
touch src/server/tools/weather_tools.py
  1. Define your tools:
# src/server/tools/weather_tools.py
from fastmcp import FastMCP

weather_mcp = FastMCP("Weather Tools")

@weather_mcp.tool
def get_forecast(city: str, days: int = 5) -> dict:
    """Get weather forecast for specified days."""
    # Implementation here
    pass
  1. Mount in main app:
# src/server/app.py
from src.server.tools.weather_tools import weather_mcp

# Add this line with other mounts
app.mount(weather_mcp)

Environment Configuration

Copy .env.example to .env and customize:

# MCP Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8001

# API Keys (for external services)
OPENAI_API_KEY=sk-your-key-here
WEATHER_API_KEY=your-weather-key
DATABASE_URL=postgresql://user:pass@localhost/db

CORS Configuration

The generated fastmcp.json includes CORS support for common development ports:

{
  "server": {
    "cors": {
      "enabled": true,
      "origins": [
        "http://localhost:3000",  // React
        "http://localhost:8080",  // Vue.js
        "http://localhost:4200",  // Angular
        "http://localhost:1420",  // Tauri
        "http://localhost:8000"   // FastAPI
      ]
    }
  }
}

šŸ› Troubleshooting

Common Issues

1. Import Errors

Problem: ModuleNotFoundError: No module named 'src'

Solution: Make sure you're running from the project root directory:

cd my_mcp_server
python src/server/app.py  # Not python app.py
2. Port Already in Use

Problem: Address already in use: ('localhost', 8001)

Solution:

# Find process using port 8001
netstat -ano | findstr :8001  # Windows
lsof -i :8001                 # Linux/Mac

# Kill the process or change port in .env
MCP_SERVER_PORT=8002
3. MCP Inspector Connection Issues

Problem: Inspector can't connect to server

Solution:

  1. Ensure server is running with HTTP transport
  2. Use correct URL: http://localhost:8001/mcp
  3. Check firewall settings
4. Module Import Issues

Problem: Tools not loading properly

Solution: Ensure all directories have __init__.py files (automatically created by the script).

Debug Mode

Enable debug logging by modifying app.py:

import logging
logging.basicConfig(level=logging.DEBUG)

āœ… Best Practices

1. Project Organization

  • Keep tools focused on single responsibilities
  • Group related tools in the same module
  • Use descriptive names for tools and parameters
  • Include comprehensive docstrings

2. Error Handling

@calculator_mcp.tool
def divide(a: float, b: float) -> float:
    """Divide two numbers."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

3. Type Hints

Always use type hints for better MCP integration:

from typing import List, Dict, Optional

@calculator_mcp.tool
def process_data(items: List[str], config: Optional[Dict] = None) -> Dict:
    """Process a list of items with optional configuration."""
    # Implementation
    pass

4. Testing

Create comprehensive tests:

def test_calculator_tools():
    assert add(2, 3) == 5
    assert subtract(5, 2) == 3

    # Test edge cases
    assert add(0, 0) == 0
    assert subtract(-1, -1) == 0

5. Documentation

  • Update README.md with your specific tools
  • Document API endpoints and parameters
  • Include usage examples
  • Explain environment setup

šŸ”„ Integration Examples

FastAPI Backend Integration

# In your FastAPI app
import httpx
from fastapi import FastAPI

app = FastAPI()

@app.post("/calculate")
async def calculate(operation: str, a: float, b: float):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"http://localhost:8001/mcp/tools/{operation}",
            json={"a": a, "b": b}
        )
        return response.json()

React Frontend Integration

// React component
const Calculator = () => {
  const [result, setResult] = useState(null);

  const calculate = async (operation, a, b) => {
    const response = await fetch('/api/calculate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ operation, a, b })
    });

    const data = await response.json();
    setResult(data.result);
  };

  return (
    <div>
      <button onClick={() => calculate('add', 5, 3)}>
        Add 5 + 3
      </button>
      {result && <p>Result: {result}</p>}
    </div>
  );
};

šŸ“š Resources

Official Documentation

Learning Resources

Community

šŸŽÆ Next Steps

After creating your first MCP server:

  1. Extend the Calculator

    • Add multiplication, division, power operations
    • Implement scientific calculator functions
    • Add unit conversion tools

  2. Create Domain-Specific Servers

    • Weather service with real API integration
    • Database query tools
    • File management system
    • API testing tools

  3. Advanced Features

    • Authentication and authorization
    • Rate limiting
    • Caching mechanisms
    • WebSocket support for real-time tools

  4. Production Deployment

    • Docker containerization
    • Cloud deployment (AWS, GCP, Azure)
    • Load balancing
    • Monitoring and logging

šŸ† Conclusion

The create_mcp_project.py script provides a solid foundation for building MCP servers. Start with the generated calculator example, understand the three core components (tools, resources, prompts), and gradually expand your server's capabilities.

Remember: MCP servers are all about making AI assistants more capable by giving them access to external tools and information. Start simple, test thoroughly, and build incrementally!

Happy MCP Development! šŸš€

For questions or issues, check the troubleshooting section or refer to the official resources.