a2a-server-config

# A2A Server Configuration

Provides complete patterns and templates for configuring Agent-to-Agent (A2A) servers with different transport mechanisms (HTTP, STDIO, SSE, WebSocket) following MCP (Model Context Protocol) standards.

## Security: API Key Handling

**CRITICAL:** When generating any configuration files or code:

- NEVER hardcode actual API keys or secrets
- NEVER include real credentials in examples
- NEVER commit sensitive values to git

- ALWAYS use placeholders: `your_service_key_here`
- ALWAYS create `.env.example` with placeholders only
- ALWAYS add `.env*` to `.gitignore` (except `.env.example`)
- ALWAYS read from environment variables in code
- ALWAYS document where to obtain keys

**Placeholder format:** `{service}_{env}_your_key_here`

## Instructions

### Phase 1: Analyze Requirements

Determine server configuration needs:

1. **Transport Type**
   - HTTP: Remote access, REST-like communication, CORS support
   - STDIO: Local process communication, pipe-based I/O
   - SSE (Server-Sent Events): Real-time streaming, one-way server push
   - WebSocket: Bidirectional real-time communication

2. **Framework Detection**
   - Python: FastAPI, Flask, Starlette
   - TypeScript: Express, Fastify, Node.js native http
   - Detect from package.json or requirements.txt

3. **Configuration Needs**
   - Port and host settings
   - CORS configuration
   - Authentication requirements
   - Environment variables

### Phase 2: Select and Load Templates

Based on requirements, use templates from `templates/`:

**Python Templates:**
- `templates/python-http-server.py` - FastAPI HTTP server
- `templates/python-stdio-server.py` - STDIO transport
- `templates/python-sse-server.py` - SSE streaming
- `templates/python-websocket-server.py` - WebSocket bidirectional

**TypeScript Templates:**
- `templates/typescript-http-server.ts` - Express HTTP server
- `templates/typescript-stdio-server.ts` - STDIO transport
- `templates/typescript-sse-server.ts` - SSE streaming
- `templates/typescript-websocket-server.ts` - WebSocket bidirectional

### Phase 3: Configure Transport

Apply configuration based on transport type:

**HTTP Configuration:**
```python
# Python (FastAPI)
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True
    )
```

```typescript
// TypeScript (Express)
const PORT = process.env.PORT || 8000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
```

**STDIO Configuration:**
```python
# Python
mcp.run(transport="stdio")
```

```typescript
// TypeScript
server.connect(new StdioServerTransport());
```

**SSE Configuration:**
```python
# Python
@app.get("/events")
async def events():
    return EventSourceResponse(event_generator())
```

**WebSocket Configuration:**
```python
# Python
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
```

### Phase 4: Add CORS and Security

For HTTP/SSE/WebSocket servers:

```python
# Python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Configure appropriately
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

```typescript
// TypeScript
import cors from 'cors';
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
}));
```

### Phase 5: Environment Configuration

Create `.env.example` with placeholders:

```bash
# Server Configuration
PORT=8000
HOST=0.0.0.0
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# API Keys (NEVER commit real values)
ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here

# Transport Settings
TRANSPORT_TYPE=http
ENABLE_CORS=true
```

### Phase 6: Validation

Run validation script:
```bash
bash scripts/validate-config.sh <server-file>
```

Checks:
- No hardcoded API keys
- Environment variable usage
- CORS configuration
- Transport setup validity
- .gitignore includes .env files

## Scripts

- `scripts/validate-config.sh` - Validate server configuration
- `scripts/generate-server.sh` - Generate server from template
- `scripts/test-transport.sh` - Test transport connectivity

## Templates

**Python:**
- `templates/python-http-server.py` - HTTP server with FastAPI
- `templates/python-stdio-server.py` - STDIO transport
- `templates/python-sse-server.py` - SSE streaming server
- `templates/python-websocket-server.py` - WebSocket server

**TypeScript:**
- `templates/typescript-http-server.ts` - HTTP server with Express
- `templates/typescript-stdio-server.ts` - STDIO transport
- `templates/typescript-sse-server.ts` - SSE streaming server
- `templates/typescript-websocket-server.ts` - WebSocket server

## Examples

- `examples/http-fastapi-example.md` - Complete HTTP server with FastAPI
- `examples/stdio-simple-example.md` - Basic STDIO server
- `examples/sse-streaming-example.md` - SSE streaming configuration
- `examples/websocket-bidirectional-example.md` - WebSocket bidirectional communication

## Requirements

- Framework-specific dependencies (FastAPI/Express/etc.)
- CORS middleware for HTTP/SSE/WebSocket
- Environment variable management (python-dotenv/dotenv)
- No hardcoded API keys or secrets
- .gitignore protection for sensitive files

## Use Cases

1. **Setting up HTTP server for remote A2A communication**
   - Load http template
   - Configure CORS
   - Set environment variables
   - Validate configuration

2. **Configuring STDIO for local agent communication**
   - Load stdio template
   - Configure process pipes
   - Test connectivity

3. **Implementing SSE for real-time agent updates**
   - Load sse template
   - Configure event streams
   - Set up CORS
   - Test streaming

4. **Setting up WebSocket for bidirectional agent chat**
   - Load websocket template
   - Configure connection handling
   - Set up authentication
   - Test bidirectional flow