Claude Integration with MCP Server

Overview

This project serves as a reference implementation of the Model Context Protocol (MCP), enabling seamless tool calling between Large Language Models (LLMs) and applications. It features a client/server architecture with HTTP APIs, local CLI execution, and integration with AWS Bedrock and Claude 3.7.

AI-Assisted Development

The project was developed with the assistance of Claude 3.7, Anthropic's advanced AI assistant. The llm/ directory contains design specifications, implementation plans, and technical decisions, providing insight into the AI-assisted development process.

Project Structure

mcp-example/
├── core/                 # Core protocol implementation
│   ├── schema.py         # Protocol schema definitions
│   ├── validation.py     # Schema validation utilities
│   ├── registry.py       # Tool registry
│   └── executor.py       # Tool executor
├── tools/                # Tool implementations
│   ├── calculator.py     # Calculator tool
│   └── text.py           # Text processing tool
├── adapters/             # Interface adapters
│   ├── stdio/            # Command-line interface
│   └── http/             # HTTP client for remote servers
├── server/               # Server implementation
│   ├── app.py            # FastAPI server
│   └── main.py           # Server runner
├── examples/             # Usage examples
├── tests/                # Test suite
└── llm/                  # Implementation documentation

Getting Started

Prerequisites

• Python 3.10 or higher
• Poetry (for dependency management)

Installation

1. Clone the repository:
   bash git clone https://github.com/yourusername/mcp-example.git cd mcp-example
2. Set up a virtual environment and install dependencies:
3. Using Poetry:
   bash poetry install
4. Using venv:
   bash python3 -m venv venv source venv/bin/activate # On Windows, use: venv\Scripts\activate pip install -e .

Running the CLI

# With Poetry
poetry run python -m mcp_example.adapters.stdio.cli

# With venv
python -m mcp_example.adapters.stdio.cli

Running the Server

# With Poetry
poetry run python -m mcp_example.server.main --host 0.0.0.0 --port 8000

# With venv
python -m mcp_example.server.main --host 0.0.0.0 --port 8000

Testing the Server

1. List available functions:
   bash curl -X GET http://localhost:8000/api/functions -H "X-API-Key: test-key"
2. Call the calculator function:
   bash curl -X POST http://localhost:8000/api/functions/call \ -H "X-API-Key: test-key" \ -H "Content-Type: application/json" \ -d '{"name": "calculator", "parameters": {"operation": "add", "a": 5, "b": 3}}'

API Endpoints

• GET /api/functions: List all available functions
• POST /api/functions/call: Call a function
• WebSocket /api/functions/stream: Stream function results

Using the HTTP Client

from mcp_example.adapters.http.client import MCPClient

client = MCPClient(base_url="http://localhost:8000", api_key="test-key")
functions = client.list_functions()
response = client.call_function(name="calculator", parameters={"operation": "add", "a": 5, "b": 3})
print(f"Result: {response.result}")

WebSocket Streaming

import asyncio
from mcp_example.adapters.http.client import AsyncMCPClient

async def main():
    client = AsyncMCPClient("http://localhost:8000", api_key="test-key")
    async for chunk in client.stream_function(name="long_running_operation", parameters={"duration": 5}):
        print(f"Progress: {chunk.result}")
    await client.close()

asyncio.run(main())

AWS Bedrock and Claude 3.7 Integration

1. Create an AWS Account and Enable Bedrock
2. Configure AWS Credentials:
   bash export AWS_ACCESS_KEY_ID="your-access-key" export AWS_SECRET_ACCESS_KEY="your-secret-key" export AWS_DEFAULT_REGION="us-west-2"

Using Claude 3.7 with MCP

from mcp_example.adapters.aws.claude import ClaudeAdapter, ClaudeMessage, ClaudeRole
from mcp_example.core.schema import FunctionDefinition

adapter = ClaudeAdapter()
messages = [ClaudeMessage(role=ClaudeRole.USER, content="What's 42 + 7?")]
calculator_function = FunctionDefinition(name="calculator", description="Performs arithmetic operations", parameters={"type": "object", "properties": {"operation": {"type": "string", "enum": ["add", "subtract", "multiply", "divide"], "description": "The operation to perform"}, "a": {"type": "number", "description": "First operand"}, "b": {"type": "number", "description": "Second operand"}}, "required": ["operation", "a", "b"]})
response = adapter.generate(messages, functions=[calculator_function])
function_calls = adapter.extract_function_calls(response)
for call in function_calls:
    print(f"Function: {call.name}, Parameters: {call.parameters}")

Proxy Tool

from mcp_example.core.executor import execute
from mcp_example.tools.proxy import register

register()
result = execute({"name": "proxy", "parameters": {"server_url": "http://remote-server.com", "api_key": "remote-server-key", "function_name": "calculator", "parameters": {"operation": "add", "a": 5, "b": 3}}})
print(f"Result from remote server: {result}")

Tool Chaining

from mcp_example.core.executor import execute

calc_result = execute({"name": "calculator", "parameters": {"operation": "add", "a": 5, "b": 3}})
text_result = execute({"name": "transform_text", "parameters": {"operation": "append", "text": "The result is: ", "append_text": str(calc_result)}})
print(text_result)  # Output: "The result is: 8"

Available Tools

Calculator

Performs basic arithmetic operations: add, subtract, multiply, divide, power, sqrt, log.

Text Processing

Provides text transformation and analysis: uppercase, lowercase, capitalize, title, reverse, count_chars, count_words, trim, replace.

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

A reference implementation of the Model Context Protocol (MCP) enabling seamless tool calling between LLMs and applications. Features client/server architecture with HTTP APIs, local CLI execution, and AWS Bedrock integration in a production-ready, extensible framework.