mcp-server-project by nkaluva9 - MCP Server

MCP Server Project

This is a Model Context Protocol (MCP) server that demonstrates basic functionality including resources and tools. The project has been properly configured with a virtual environment and renamed from "untitled" to "mcp-server-project".

Project Setup ✅

✅ Virtual environment created and activated (venv/)
✅ Python interpreter configured
✅ Project renamed to "mcp-server-project"
✅ All dependencies installed
✅ Tests passing

What is MCP?

Model Context Protocol (MCP) is a protocol that allows AI assistants to connect to external data sources and tools. It provides a standardized way for AI models to access and interact with various services and resources.

Features

This MCP server provides:

Resources

Greeting Resource: A simple greeting message
Server Info: JSON information about the server

Tools

echo: Echo back any text you provide
add_numbers: Add two numbers together
get_current_time: Get the current date and time

Setup

Quick Start

Activate the virtual environment (already created):

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

Verify installation (dependencies already installed):
```
pip list
```
Install/Update dependencies (if needed):
```
pip install -r requirements.txt
```

Running the Server

Method 1: Standard MCP Server (Recommended)

python mcp_server.py

Starts the server in standard MCP mode
Waits silently for MCP client connections via stdin/stdout
This is normal behavior - the server appears to "hang" but is actually listening
Press Ctrl+C to stop the server

Method 2: Verbose MCP Server (Shows Status)

python mcp_server_verbose.py

Same functionality as the standard server
Shows startup messages and status information
Helpful for debugging and confirming the server is running

Method 3: Direct Server Runner (PyCharm Friendly)

python run_mcp_server.py

Designed to run easily in PyCharm
Includes error handling and diagnostic information
Shows clear status messages

Method 4: Using Batch Files (Windows)

Double-click any of these files:

run_server.bat - Tries multiple Python commands automatically
run_server.ps1 - PowerShell version with better error handling

Testing the Server

Method 1: Comprehensive Test Suite

python test_client.py

Expected Output:

✓ MCP server imported successfully

1. Testing list_resources...
✓ Found 2 resources:
  - Greeting Resource: A simple greeting message
  - Server Info: Information about this MCP server

2. Testing read_resource...
✓ Greeting resource: Hello! This is a greeting from your MCP server.

3. Testing list_tools...
✓ Found 3 tools:
  - echo: Echo back the input text
  - add_numbers: Add two numbers together
  - get_current_time: Get the current date and time

4. Testing tool calls...
✓ Echo tool: Echo: Hello, MCP!
✓ Add numbers tool: The sum of 5 and 3 is 8
✓ Current time tool: Current time: 2025-09-28 17:08:49

🎉 All tests passed! Your MCP server is working correctly.

Method 2: Diagnostic Test

python diagnose_mcp.py

Tests all MCP imports and dependencies
Verifies server creation and functionality
Shows detailed diagnostic information
Helpful for troubleshooting issues

Method 3: Import Test

python test_imports.py

Basic test to verify all imports work correctly
Quick way to check if dependencies are installed

Understanding MCP Server Behavior

Normal Behavior

When you run python mcp_server.py:

✅ The server starts successfully (no error messages)
✅ It enters "listening mode" waiting for JSON-RPC messages via stdin
✅ The terminal appears to "hang" or show no response - THIS IS NORMAL
✅ The server is ready to accept MCP client connections

What "No Response" Means

NOT an error - MCP servers are designed to wait silently
Normal behavior - servers communicate via stdin/stdout protocol
Ready state - the server is listening for MCP client connections

Development

Project Structure

mcp-server-project/
├── venv/                    # Virtual environment (created)
├── mcp_server.py           # Main MCP server (standard)
├── mcp_server_verbose.py   # MCP server with status messages
├── test_client.py          # Comprehensive test suite
├── diagnose_mcp.py         # Diagnostic and troubleshooting tool
├── run_mcp_server.py       # PyCharm-friendly server runner
├── run_direct.py           # Direct server execution tool
├── test_imports.py         # Import verification test
├── run_server.bat          # Windows batch file runner
├── run_server.ps1          # PowerShell runner script
├── requirements.txt        # Dependencies
├── pyproject.toml          # Project configuration
├── setup.py               # Setup script
├── mcp_config.json        # MCP client configuration
├── README.md              # This file
└── .gitignore             # Git ignore file

Running Tests in Different Ways

Command Line

# Full test suite
python test_client.py

# Diagnostic test
python diagnose_mcp.py

# Import verification
python test_imports.py

In PyCharm

Right-click on any test file in Project Explorer
Select "Run '[filename]'"
View results in the Run window

Installing as Package

pip install -e .

Server Configuration

For MCP Clients

The mcp_config.json file shows how this server can be configured in an MCP client:

{
  "mcpServers": {
    "mcp-server-project": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": null,
      "cwd": "."
    }
  }
}

Integration with AI Assistants

Add the server configuration to your MCP client
The server will be available as "mcp-server-project"
AI assistants can use the resources and tools provided

Extending the Server

Add new functionality by modifying mcp_server.py:

Adding Resources

@server.list_resources()
async def handle_list_resources() -> List[Resource]:
    return [
        # Add your new resources here
        Resource(
            uri="resource://example/my-resource",
            name="My Resource",
            description="Description of my resource",
            mimeType="text/plain",
        ),
        # ...existing resources...
    ]

Adding Tools

@server.list_tools()
async def handle_list_tools() -> List[Tool]:
    return [
        # Add your new tools here
        Tool(
            name="my_tool",
            description="Description of my tool",
            inputSchema={
                "type": "object",
                "properties": {
                    "param": {"type": "string", "description": "Parameter description"}
                },
                "required": ["param"]
            }
        ),
        # ...existing tools...
    ]

Implementing Tool Logic

@server.call_tool()
async def handle_call_tool(request: CallToolRequest) -> List[TextContent]:
    if request.name == "my_tool":
        param = request.arguments.get("param", "")
        result = f"Processed: {param}"
        return [TextContent(type="text", text=result)]
    # ...existing tool implementations...

Troubleshooting

Python Interpreter Issues

If PyCharm shows "No Python interpreter configured":

Go to File → Settings → Project → Python Interpreter
Click the gear icon and select "Add..."
Choose "Existing environment"
Navigate to venv\Scripts\python.exe (Windows) or venv/bin/python (macOS/Linux)

Virtual Environment Issues

# Deactivate current environment
deactivate

# Recreate virtual environment
python -m venv venv

# Activate and reinstall
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Common Issues and Solutions

"No module named 'mcp'" Error

# Install MCP dependencies
pip install -r requirements.txt

"Python not found" Error

Try these Python commands in order:

python mcp_server.py    # Standard
py mcp_server.py        # Python launcher
python.exe mcp_server.py # Explicit executable

Server Appears to "Hang"

This is normal! MCP servers wait for client connections. To verify it's working:

python test_client.py   # This will confirm everything works

Terminal/PowerShell Issues

Use the provided scripts:

# Windows batch file
run_server.bat

# PowerShell script
run_server.ps1

# Or run in PyCharm directly

Verification Commands

Check if everything is working:

# 1. Test all functionality
python test_client.py

# 2. Run diagnostics
python diagnose_mcp.py

# 3. Start server (will wait for clients - this is normal)
python mcp_server.py

Expected test results:

✅ All imports successful
✅ 2 resources found and readable
✅ 3 tools found and functional
✅ All tool calls return correct results

Next Steps

Immediate

✅ Your MCP server is fully functional and ready to use
✅ All tests pass - the server works correctly
✅ Server starts and waits for MCP clients (normal behavior)

Future Enhancements

Add custom tools and resources for your specific use case
Integrate with external APIs or databases
Add authentication and security features
Create more sophisticated data processing capabilities
Build custom MCP clients to interact with your server

Integration

Configure MCP clients to use your server
Connect with AI assistants that support MCP
Build applications that leverage your server's capabilities