# 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/)
