# Darwin Standards MCP Server

MCP server providing standards documentation and validation tools for the Darwin platform.

## Overview

The Standards MCP Server is designed to:
1. **Expose standards as MCP resources** - Agents can read platform standards via standard URIs
2. **Provide validation tools** - Validate naming conventions, tool definitions, and agent cards
3. **Enable standards search** - Find relevant standards documentation quickly

> **Note**: This is an MCP Server, not a true Agent. It provides tools and resources but does not contain an LLM and does not make autonomous decisions.

## Quick Start

### Option 1: Docker (Recommended for local development)

```bash
# Build and run
make build
make run

# Or with docker directly
docker build -t standards-mcp-server .
docker run -p 8080:8080 \
  -v /path/to/standards:/app/standards:ro \
  -e MCP_TRANSPORT=http \
  standards-mcp-server
```

### Option 2: Local Installation

```bash
# Create virtual environment and install
make install

# Run locally (stdio mode)
make run-local

# Run locally (HTTP mode)
make run-http
```

### Option 3: Claude Code Integration

```bash
# Using Python module directly
claude mcp add --transport stdio \
  --env STANDARDS_PATH=/path/to/docs/standards \
  standards -- python -m standards_mcp_server.server

# Using container
claude mcp add --transport stdio standards -- \
  docker run --rm -i \
  -v /path/to/docs/standards:/app/standards:ro \
  -e MCP_TRANSPORT=stdio \
  fgsansharedacrdeveus.azurecr.io/standards-mcp-server:latest
```

## MCP Resources

### Standards Documentation

| URI | Description |
|-----|-------------|
| `standards://agents/design` | Agent design principles |
| `standards://agents/communication` | A2A protocol standards |
| `standards://agents/tools` | MCP tool integration |
| `standards://agents/memory` | Neo4j memory architecture |
| `standards://agents/observability` | OpenTelemetry setup |
| `standards://agents/security` | Security requirements |
| `standards://mcp/server-design` | MCP server architecture |
| `standards://mcp/tool-design` | Tool definition standards |
| `standards://mcp/resource-design` | Resource exposure standards |
| `standards://mcp/security` | MCP security patterns |
| `standards://mcp/error-handling` | Error handling standards |

### Templates and Implementations

| URI | Description |
|-----|-------------|
| `templates://mcp/python` | Python MCP server template |
| `templates://mcp/dotnet` | .NET MCP server template |
| `implementations://mcp/standards` | This server's implementation |
| `implementations://agents/python/langchain` | LangChain agent |

## MCP Tools

### Validation Tools

- **`validate_azure_resource_name`** - Validate Azure resource names against naming conventions
- **`validate_mcp_tool_definition`** - Validate MCP tool definitions against standards
- **`validate_agent_card`** - Validate A2A agent cards against protocol standards

### Search Tools

- **`search_standards`** - Full-text search across standards documents
- **`list_standards_categories`** - List all available categories
- **`get_standards_summary`** - Get document summaries for a category

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_SERVER_NAME` | Server name | `standards-mcp-server` |
| `MCP_TRANSPORT` | Transport type (`stdio` or `http`) | `stdio` |
| `MCP_PORT` | HTTP port | `8080` |
| `MCP_HOST` | HTTP host | `0.0.0.0` |
| `MCP_LOG_LEVEL` | Log level | `INFO` |
| `STANDARDS_PATH` | Path to standards docs | `docs/standards` |
| `REFERENCE_IMPLEMENTATIONS_PATH` | Path to implementations | `reference-implementations` |
| `OTEL_ENABLED` | Enable OpenTelemetry | `true` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint | `null` |

## Development

### Running Tests

```bash
# Run all tests
make test

# With coverage
make test-cov

# Linting
make lint

# Type checking
make typecheck
```

### Project Structure

```
darwin-standards-mcp/
├── .github/
│   ├── workflows/          # CI/CD pipelines
│   └── PULL_REQUEST_TEMPLATE.md
├── .k8s/
│   ├── base/              # Base Kubernetes manifests
│   └── overlays/          # Environment-specific overlays
│       ├── dev/
│       └── prod/
├── src/standards_mcp_server/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── config.py          # Configuration
│   ├── observability.py   # OpenTelemetry setup
│   ├── resources/         # MCP resources
│   └── tools/             # MCP tools
├── tests/
├── scripts/               # Deployment scripts
├── docs/                  # Documentation
├── Dockerfile
├── Makefile
└── pyproject.toml
```

## Deployment

### Deploy to AKS

```bash
# Using make
make deploy

# Using script
./scripts/deploy-to-aks.sh
```

### Manual Deployment

```bash
# Get AKS credentials
az aks get-credentials --resource-group rg-fgsan-shared-dev-eus --name fgsan-shared-aks-dev-eus

# Apply manifests
kubectl apply -k .k8s/overlays/dev

# Verify
kubectl get pods -n darwin-mcp -l app=standards-mcp-server
```

See [DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions.

## CI/CD

The repository includes GitHub Actions workflows for:

- **lint-and-test.yml** - Runs on PRs: linting, testing, type checking
- **build-and-push.yml** - Runs on push to main: builds and pushes Docker image to ACR
- **deploy-to-aks.yml** - Runs after build: deploys to AKS
- **release.yml** - Runs on version tags: creates GitHub releases

## License

MIT License - see [LICENSE](LICENSE) for details.

## Related

- [Darwin Platform Documentation](https://github.com/darwin-platform/docs)
- [MCP Specification](https://spec.modelcontextprotocol.io/)