Skip to content

Building AI agents, atomically

Improve docs & remove local deployment script

KennyVaneetvelde06db75cc894c
diff --git a/build_and_deploy.ps1 b/build_and_deploy.ps1
deleted file mode 100644
index 1a73bf6..0000000
--- a/build_and_deploy.ps1
+++ /dev/null
@@ -1,117 +0,0 @@
-# Function to update version in a file
-function Update-VersionInFile {
- param (
- [string]$Version,
- [string]$FilePath
- )
- (Get-Content $FilePath) -replace 'version = ".*"', "version = `"$Version`"" | Set-Content $FilePath
- Write-Host "Updated version in $FilePath to $Version"
-}
-
-# Function to update (increment) version
-function Update-Version {
- param (
- [string]$Version,
- [string]$ReleaseType
- )
-
- $versionParts = $Version -split '\.'
- $major = [int]$versionParts[0]
- $minor = [int]$versionParts[1]
- $patch = [int]$versionParts[2]
-
- switch ($ReleaseType) {
- "major" {
- $major++
- $minor = 0
- $patch = 0
- }
- "minor" {
- $minor++
- $patch = 0
- }
- "patch" {
- $patch++
- }
- default {
- Write-Host "Invalid release type. Use 'major', 'minor', or 'patch'."
- exit 1
- }
- }
-
- return "$major.$minor.$patch"
-}
-
-# Function to set PyPI token
-function Set-PyPIToken {
- if (-not $env:PYPI_TOKEN) {
- Write-Host "Error: PYPI_TOKEN environment variable is not set."
- exit 1
- }
- poetry config pypi-token.pypi $env:PYPI_TOKEN
- Write-Host "PyPI token configured successfully."
-}
-
-# Add this function at the beginning of the script
-function Import-EnvFile {
- $envFile = ".env"
- if (Test-Path $envFile) {
- Get-Content $envFile | ForEach-Object {
- if ($_ -match '^([^=]+)=(.*)$') {
- $name = $matches[1]
- $value = $matches[2]
- Set-Item -Path "env:$name" -Value $value
- }
- }
- Write-Host "Environment variables loaded from .env file."
- }
- else {
- Write-Host "Warning: .env file not found."
- }
-}
-
-# Call this function before any other operations in the script
-Import-EnvFile
-
-# Check if release type is provided
-if ($args.Count -eq 0) {
- Write-Host "Please specify a release type (major, minor, or patch)"
- exit 1
-}
-
-$releaseType = $args[0]
-
-# Validate release type
-if ($releaseType -notin @("major", "minor", "patch")) {
- Write-Host "Invalid release type. Use 'major', 'minor', or 'patch'."
- exit 1
-}
-
-# Get current version from pyproject.toml
-$currentVersion = (Select-String -Path "pyproject.toml" -Pattern 'version = "(.+)"').Matches.Groups[1].Value
-
-# Calculate new version
-$newVersion = Update-Version -Version $currentVersion -ReleaseType $releaseType
-
-Write-Host "Updating version from $currentVersion to $newVersion"
-
-# Update version in files
-Update-VersionInFile -Version $newVersion -FilePath "pyproject.toml"
-
-# Build the consolidated package
-Write-Host "Building consolidated atomic-agents package..."
-
-# Create a new virtualenv in the project directory and install dependencies
-poetry install
-
-# Build the package
-poetry build
-
-# Before publishing, set the PyPI token
-Set-PyPIToken
-
-# Upload to PyPI
-Write-Host "Uploading atomic-agents to PyPI..."
-poetry publish
-
-Write-Host "Build and deploy process completed successfully!"
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 03d4e5a..a2770d1 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -96,3 +96,16 @@ Coordinate multiple agents for complex tasks:
- Result aggregation
[View Orchestration Examples](https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-examples/orchestration-agent)
+
+## MCP Agent
+
+Build intelligent agents using the Model Context Protocol:
+
+- Server implementation with multiple transport methods
+- Dynamic tool discovery and registration
+- Natural language query processing
+- Stateful conversation handling
+- Extensible tool architecture
+
+[View MCP Agent Documentation](mcp_agent.md)
+[View MCP Agent Examples](https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-examples/mcp-agent)
diff --git a/docs/examples/mcp_agent.md b/docs/examples/mcp_agent.md
new file mode 100644
index 0000000..617178e
--- /dev/null
+++ b/docs/examples/mcp_agent.md
@@ -0,0 +1,336 @@
+# MCP Server and Client Example
+
+This guide provides a detailed overview of the Model Context Protocol (MCP) server and client example implementation in the Atomic Agents framework.
+
+## Overview
+
+The MCP example demonstrates how to build an intelligent agent system using the Model Context Protocol, showcasing both server and client implementations. The example supports two transport methods: STDIO and Server-Sent Events (SSE).
+
+## Architecture
+
+### MCP Server
+
+The server component (`example-mcp-server`) is built using:
+- FastMCP: A high-performance MCP server implementation
+- Starlette: A lightweight ASGI framework
+- Uvicorn: An ASGI server implementation
+
+Key components:
+1. **Transport Layers**:
+ - `server_stdio.py`: Implements STDIO-based communication
+ - `server_sse.py`: Implements SSE-based HTTP communication
+
+2. **Tools Service**:
+ - Manages registration and execution of MCP tools
+ - Handles tool discovery and metadata
+
+3. **Resource Service**:
+ - Manages static resources
+ - Handles resource discovery and access
+
+4. **Built-in Tools**:
+ - `AddNumbersTool`: Performs addition
+ - `SubtractNumbersTool`: Performs subtraction
+ - `MultiplyNumbersTool`: Performs multiplication
+ - `DivideNumbersTool`: Performs division
+
+### MCP Client
+
+The client component (`example-client`) is an intelligent agent that:
+
+1. **Tool Discovery**:
+ - Dynamically discovers available tools from the MCP server
+ - Builds a schema-based tool registry
+
+2. **Query Processing**:
+ - Uses GPT models for natural language understanding
+ - Extracts parameters from user queries
+ - Selects appropriate tools based on intent
+
+3. **Execution Flow**:
+ - Maintains conversation context
+ - Handles tool execution results
+ - Provides conversational responses
+
+## Implementation Details
+
+### Server Implementation
+
+The server supports two transport methods:
+
+1. **SSE Transport** (`server_sse.py`):
+```python
+# Initialize FastMCP server
+mcp = FastMCP("example-mcp-server")
+
+# Register tools and resources
+tool_service.register_tools(get_available_tools())
+resource_service.register_resources(get_available_resources())
+
+# Create Starlette app with CORS support
+app = create_starlette_app(mcp_server)
+```
+
+2. **STDIO Transport** (`server_stdio.py`):
+- Runs as a subprocess
+- Communicates through standard input/output
+- Ideal for local development
+
+### Client Implementation
+
+The client uses a sophisticated orchestration system:
+
+1. **Tool Management**:
+```python
+# Fetch available tools
+tools = fetch_mcp_tools(
+ mcp_endpoint=config.mcp_server_url,
+ use_stdio=False,
+)
+
+# Build tool schema mapping
+tool_schema_to_class_map = {
+ ToolClass.input_schema: ToolClass
+ for ToolClass in tools
+ if hasattr(ToolClass, "input_schema")
+}
+```
+
+2. **Query Processing**:
+- Uses an orchestrator agent to analyze queries
+- Extracts parameters and selects appropriate tools
+- Maintains conversation context through AgentMemory
+
+## MCP Transport Methods
+
+The example implements two distinct transport methods, each with its own advantages:
+
+### 1. STDIO Transport
+
+STDIO transport uses standard input/output streams for communication between the client and server:
+
+```python
+# Client-side STDIO setup (from main_stdio.py)
+async def _bootstrap_stdio():
+ stdio_exit_stack = AsyncExitStack()
+ command_parts = shlex.split(config.mcp_stdio_server_command)
+ server_params = StdioServerParameters(command=command_parts[0], args=command_parts[1:], env=None)
+ read_stream, write_stream = await stdio_exit_stack.enter_async_context(stdio_client(server_params))
+ session = await stdio_exit_stack.enter_async_context(ClientSession(read_stream, write_stream))
+ await session.initialize()
+ return session
+```
+
+**Key advantages**:
+- No network configuration required
+- Simple local setup
+- Direct process communication
+- Lower latency for local usage
+
+**Use cases**:
+- Development and testing
+- Single-user environments
+- Embedded agent applications
+- Offline operation
+
+### 2. SSE Transport
+
+Server-Sent Events (SSE) transport uses HTTP long-polling for real-time, one-way communication:
+
+```python
+# Server-side SSE setup (from server_sse.py)
+async def handle_sse(request: Request) -> None:
+ async with sse.connect_sse(
+ request.scope,
+ request.receive,
+ request._send, # noqa: SLF001
+ ) as (read_stream, write_stream):
+ await mcp_server.run(
+ read_stream,
+ write_stream,
+ mcp_server.create_initialization_options(),
+ )
+```
+
+**Key advantages**:
+- Multiple clients can connect to a single server
+- Network-based communication
+- Stateless server architecture
+- Suitable for distributed systems
+
+**Use cases**:
+- Production deployments
+- Multi-user environments
+- Scalable agent infrastructure
+- Cross-network operation
+
+## Tool Interface
+
+The MCP server defines a standardized tool interface that all tools must implement:
+
+```python
+class Tool(ABC):
+ """Abstract base class for all tools."""
+ name: ClassVar[str]
+ description: ClassVar[str]
+ input_model: ClassVar[Type[BaseToolInput]]
+ output_model: ClassVar[Optional[Type[BaseModel]]] = None
+
+ @abstractmethod
+ async def execute(self, input_data: BaseToolInput) -> ToolResponse:
+ """Execute the tool with given arguments."""
+ pass
+
+ def get_schema(self) -> Dict[str, Any]:
+ """Get JSON schema for the tool."""
+ schema = {
+ "name": self.name,
+ "description": self.description,
+ "input": self.input_model.model_json_schema(),
+ }
+
+ if self.output_model:
+ schema["output"] = self.output_model.model_json_schema()
+
+ return schema
+```
+
+The tool interface consists of:
+
+1. **Class Variables**:
+ - `name`: Tool identifier used in MCP communications
+ - `description`: Human-readable tool description
+ - `input_model`: Pydantic model defining input parameters
+ - `output_model`: Pydantic model defining output structure (optional)
+
+2. **Execute Method**:
+ - Asynchronous method that performs the tool's functionality
+ - Takes strongly-typed input data
+ - Returns a structured ToolResponse
+
+3. **Schema Method**:
+ - Provides JSON Schema for tool discovery
+ - Enables automatic documentation generation
+ - Facilitates client-side validation
+
+## Configuration
+
+### Server Configuration
+
+The server can be configured through command-line arguments:
+```bash
+poetry run example-mcp-server --mode=sse --host=0.0.0.0 --port=6969 --reload
+```
+
+Options:
+- `--mode`: Transport mode (sse/stdio)
+- `--host`: Host to bind to
+- `--port`: Port to listen on
+- `--reload`: Enable auto-reload for development
+
+### Client Configuration
+
+The client uses a configuration class:
+```python
+@dataclass
+class MCPConfig:
+ mcp_server_url: str = "http://localhost:6969"
+ openai_model: str = "gpt-4o-mini"
+ openai_api_key: str = os.getenv("OPENAI_API_KEY")
+```
+
+For STDIO transport, additional options are available:
+```python
+@dataclass
+class MCPConfig:
+ openai_model: str = "gpt-4o-mini"
+ openai_api_key: str = os.getenv("OPENAI_API_KEY")
+ mcp_stdio_server_command: str = "poetry run example-mcp-server --mode stdio"
+```
+
+## Usage Examples
+
+1. **Start the Server (SSE mode)**:
+```bash
+cd example-mcp-server
+poetry run example-mcp-server --mode=sse
+```
+
+2. **Run the Client**:
+
+Using the main launcher with transport selection:
+```bash
+cd example-client
+poetry run python -m example_client.main --transport sse
+```
+
+Directly calling the SSE client:
+```bash
+cd example-client
+poetry run python -m example_client.main_sse
+```
+
+Directly calling the STDIO client:
+```bash
+cd example-client
+poetry run python -m example_client.main_stdio
+```
+
+3. **Example Queries**:
+```
+You: What is 2+2?
+You: Calculate the square root of 144
+You: Generate a random number between 1 and 100
+```
+
+## Best Practices
+
+1. **Development**:
+ - Use STDIO transport for local development
+ - Enable server auto-reload during development
+ - Implement proper error handling
+
+2. **Production**:
+ - Use SSE transport for production deployments
+ - Configure appropriate CORS settings
+ - Implement authentication if needed
+
+3. **Tool Development**:
+ - Follow the Tool interface contract
+ - Provide clear input/output schemas
+ - Include comprehensive documentation
+
+## Extending the Example
+
+To add new tools:
+
+1. Create a new tool class implementing the Tool interface
+2. Register the tool in the server's tool service
+3. The client will automatically discover and use the new tool
+
+Example tool structure:
+```python
+class MyNewTool(Tool):
+ name = "my_new_tool"
+ description = "This tool performs a custom operation"
+ input_model = create_model(
+ "MyNewToolInput",
+ param1=(str, Field(..., description="First parameter")),
+ param2=(int, Field(..., description="Second parameter")),
+ __base__=BaseToolInput
+ )
+
+ async def execute(self, input_data: BaseToolInput) -> ToolResponse:
+ # Access params with input_data.param1, input_data.param2
+ result = f"Processed {input_data.param1} with {input_data.param2}"
+ return ToolResponse.from_text(result)
+```
+
+Then register the tool in the server:
+```python
+def get_available_tools() -> List[Tool]:
+ return [
+ # ... existing tools ...
+ MyNewTool(),
+ ]
+```