Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
Clerum MCP Servers
MCP (Model Context Protocol) server implementations for the Clerum platform. These servers provide tool capabilities to LLM agents through the MCP protocol.
Overview
This directory contains MCP server implementations, test suites, and Kubernetes deployment specifications. MCP servers are deployed as Kubernetes resources managed by the Context Mapper operator.
Available Servers
| Server | Description | Transport | Port | Status |
|---|---|---|---|---|
| Airtable | Airtable API integration for bases, tables, and records | StreamableHTTP | 3000 | Tested — dedicated unit-test suite |
| MongoDB | MongoDB integration for querying, aggregation, and schema inspection | StreamableHTTP | 3000 | Tested — dedicated unit-test suite |
| Web Search | Brave Search API web/news search and page fetching (first-party source) | StreamableHTTP | 3000 | Available — no test suite yet |
| Playwright | Browser automation via the upstream Microsoft Playwright MCP image | StreamableHTTP | 8931 | Available — no test suite yet |
| Doc Generator | Markdown → print-ready HTML documents and Excel (.xlsx) generation (first-party source) | StreamableHTTP | 3000 | Source only — no image, no tests |
| Alpha Vantage | Secret template only — no Dockerfile, source, or CRD yet | — | — | Experimental stub |
"Tested" refers to the unit-test suites under __tests__/ in this package (see Testing); the servers marked "available" build and deploy but do not have test suites here yet. Doc Generator is "source only" because nothing in this repo builds or publishes an image for it: it has no row in deploy/images.json and no publish-matrix entry, so running it means building its Dockerfile yourself. Web Search and Doc Generator ship no in-tree mcpserver.yaml — see their READMEs for how to deploy them.
Project Structure
mcp-servers/
├── airtable/ # Airtable MCP server
│ ├── mcpserver.yaml # CRD specification
│ ├── example.secret.yaml # Secret template
│ └── __tests__/ # Test suite
│ ├── airtable.config.test.ts
│ ├── airtable.api.test.ts
│ ├── airtable.mcp.test.ts
│ └── airtable.k8s.test.ts
├── mongodb/ # MongoDB MCP server
│ ├── mcpserver.yaml # CRD specification
│ ├── example.secret.yaml # Secret template
│ └── __tests__/ # Test suite
│ ├── mongodb.config.test.ts
│ ├── mongodb.connection.test.ts
│ ├── mongodb.mcp.test.ts
│ └── mongodb.statefulset.test.ts
├── web-search/ # Web Search MCP server (first-party src/ + Dockerfile)
├── playwright/ # Playwright MCP server (upstream image + CRD spec)
├── doc-generator/ # Doc Generator MCP server (first-party src/ + Dockerfile)
├── alphavantage/ # Experimental stub (secret template only)
├── makefile # deploy-* / undeploy-* targets (mongodb, airtable, playwright)
├── utils/ # Shared utilities
│ └── yaml-loader.ts # YAML parser for tests
├── vitest.config.ts # Test configuration
├── package.json # Dependencies and scripts
└── README.md # This file
Quick Start
Prerequisites
- Node.js 20.x or higher
- Kubernetes cluster (for deployment)
- kubectl configured
Testing
See the Testing section below for the full test suite guide. Quick start:
npm install
npm test
Deployment
Deploy MCP servers to Kubernetes:
# Apply CRD specifications
kubectl apply -f airtable/mcpserver.yaml
kubectl apply -f mongodb/mcpserver.yaml
# Create secrets (use example.secret.yaml as templates)
kubectl apply -f airtable/secret.yaml
kubectl apply -f mongodb/secret.yaml
Configuration
MCP Server CRD
Each server is defined by a McpServer CRD:
apiVersion: clerum.io/v1alpha1
kind: McpServer
metadata:
name: airtable-server
namespace: mcp-server
spec:
contextRef: context1
description: 'Airtable MCP server for data operations'
image: your-registry.example.com/evenfire/airtable-mcp-server:latest
imagePullPolicy: Always
transport:
type: streamableHttp
url: http://airtable-server.mcp-server.svc.cluster.local:3000/mcp
port: 3000
envMapping:
transport: MCP_TRANSPORT
httpPort: PORT
envSecret:
name: mcp-airtable-credentials
keys:
- secretKey: api-key
envVar: AIRTABLE_API_KEY
resources:
requests:
memory: '128Mi'
cpu: '100m'
limits:
memory: '256Mi'
cpu: '500m'
auth:
type: none
enabled: true
Secrets
API keys and connection strings are stored as Kubernetes secrets:
apiVersion: v1
kind: Secret
metadata:
name: mcp-airtable-credentials
namespace: mcp-server
type: Opaque
data:
# Base64 encoded values
api-key: <BASE64_ENCODED_API_KEY>
Encode secrets:
echo -n "your-api-key" | base64
MCP Tools
Airtable Server
airtable_list_bases- List accessible Airtable basesairtable_list_tables- List tables in a baseairtable_list_records- List records in a tableairtable_get_record- Get a single recordairtable_create_record- Create a new recordairtable_update_record- Update an existing recordairtable_delete_record- Delete a record
MongoDB Server
mongodb_find- Query documentsmongodb_aggregate- Aggregation pipelinemongodb_count_documents- Count matching documentsmongodb_distinct- Get distinct valuesmongodb_list_collections- List collections
Transport Protocol
All servers use StreamableHTTP transport:
- Protocol: HTTP/1.1
- Path:
/mcp - Methods: POST for MCP operations
- Content-Type:
application/json
MCP Endpoints
- tools/list - List available tools
- tools/call - Execute a tool
Resource Requirements
| Server | Memory Request | Memory Limit | CPU Request | CPU Limit |
|---|---|---|---|---|
| Airtable | 128Mi | 256Mi | 100m | 500m |
| MongoDB | 128Mi | 256Mi | 100m | 500m |
| Playwright | 512Mi | 1Gi | 250m | 1000m |
Web Search and Doc Generator have no in-tree McpServer CRD, so no resource requirements are defined here.
Architecture
MCP servers are deployed as Kubernetes Deployments (or StatefulSets for stateful services like MongoDB) by the Context Mapper operator. The operator:
- Watches
McpServerCRDs - Creates Deployments/Services
- Generates NetworkPolicies for access control
- Manages secret references
Development
Adding a New MCP Server
- Create server directory:
your-server/ - Create CRD specification:
your-server/mcpserver.yaml - Create secret template:
your-server/example.secret.yaml - Create test suite:
your-server/__tests__/*.test.ts - Add test script to
package.json
Test Structure
Follow the established test pattern:
*.config.test.ts- CRD configuration validation*.api.test.ts- API interaction mocks*.mcp.test.ts- MCP protocol operations*.k8s.test.ts- Kubernetes resource generation
Security
- Secrets are never stored in CRDs
- NetworkPolicies enforce deny-by-default
- Resource limits prevent resource exhaustion
- Read-only mode enforced where applicable (e.g., MongoDB)
Monitoring
Each server exposes a health check endpoint:
http://server-name.mcp-server.svc.cluster.local:3001/health
Troubleshooting
Server Not Starting
Check pod logs:
kubectl logs -n mcp-server -l app=airtable-server
Connection Failures
Verify:
- Secret exists and has correct keys
- Service is reachable:
kubectl get svc -n mcp-server - NetworkPolicies allow traffic
Test Failures
See the Testing — Troubleshooting section below.
Testing
Complete guide for testing the MCP servers (Airtable, MongoDB) in the Clerum project. The test suite validates CRD configuration, Kubernetes resource generation, MCP protocol operations, and API interactions. Tests are organized by server type and cover both unit and integration scenarios.
Test Statistics
| Metric | Value |
|---|---|
| Total Test Cases | 343 unit tests |
| Test Framework | Vitest 4.0.18 |
| Test Environment | Node.js |
| Coverage | Configuration, API, MCP, K8s resources |
Test Files by Server
Airtable
airtable.config.test.ts— CRD and configuration validationairtable.api.test.ts— Airtable API mocking and interactionsairtable.mcp.test.ts— MCP protocol operationsairtable.k8s.test.ts— Kubernetes resource generation
MongoDB
mongodb.config.test.ts— CRD and configuration validationmongodb.connection.test.ts— MongoDB connection handlingmongodb.mcp.test.ts— MCP protocol operationsmongodb.statefulset.test.ts— StatefulSet resource generation
Prerequisites
- Node.js: Version 20.x or higher (tests use
@types/node@^20.10.0) - npm: For dependency management
- TypeScript: Version 5.3.0 or higher
cd mcp-servers
npm install
Running Tests
cd mcp-servers
# All tests
npm test
# Per-server
npm run test:airtable
npm run test:mongodb
# Watch mode (development)
npm run test:watch
# Single file
npx vitest run airtable/__tests__/airtable.config.test.ts
# With coverage (reports under coverage/)
npx vitest run --coverage
Test Categories
Tests are organized into four categories. A given server may have several or all of these files depending on what it exercises.
1. Configuration Tests (*.config.test.ts)
Validate CRD specifications, environment variable mappings, resource requirements, and secret configurations.
What they test:
- CRD metadata (API version, kind, names)
- Context references
- Transport configuration (StreamableHTTP)
- Environment variable mappings
- Secret references and key mappings
- Resource requirements (CPU, memory)
- Authentication configuration
expect(crd.apiVersion).toBe('clerum.io/v1alpha1')
expect(crd.kind).toBe('McpServer')
expect(crd.spec.transport.type).toBe('streamableHttp')
2. API Tests (*.api.test.ts)
Test external API interactions using mocks. Validate API client behavior, error handling, and rate limiting.
What they test:
- API mock setup
- Response parsing
- Error handling (rate limits, auth failures)
- Data transformation
- Retry logic
Key fixtures:
MockAirtableClient— Simulates Airtable APIMockMongoClient— Simulates MongoDB connections
3. MCP Protocol Tests (*.mcp.test.ts)
Validate MCP protocol operations including tools/list, tools/call, and session management.
What they test:
- MCP
tools/listendpoint - Tool parameter validation
- Tool execution (
tools/call) - Response formatting
- Error responses
Example MCP tools validated:
airtable_list_bases,airtable_list_tables,airtable_list_recordsmongodb_find,mongodb_aggregate,mongodb_count_documents
4. Kubernetes Tests (*.k8s.test.ts, *.statefulset.test.ts)
Validate Kubernetes resource generation (Deployments, Services, StatefulSets).
What they test:
- Deployment resource generation
- Service resource generation
- StatefulSet generation (MongoDB)
- Container configuration
- Volume mounts and claims
- Resource limits and requests
Test Utilities
YAML Loader (utils/yaml-loader.ts)
Simple YAML parser for loading test fixtures from CRD files.
import { loadYaml } from '../../utils/yaml-loader'
const crd = loadYaml(yamlContent)
expect(crd.kind).toBe('McpServer')
Mock Clients
Test files include mock implementations for:
MockAirtableClient— Airtable API mockMockMongoClient— MongoDB connection mockMockAirtableMcpServer— MCP server mock
Test Fixtures
Test fixtures are located alongside test files:
mcpserver.yaml— CRD specificationexample.secret.yaml— Secret template
Vitest Configuration (vitest.config.ts)
{
test: {
globals: true,
environment: 'node',
include: ['**/__tests__/**/*.test.ts'],
exclude: ['node_modules', 'dist'],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html']
}
}
}
Writing New Tests
import { beforeEach, describe, expect, it } from 'vitest'
import { loadYaml } from '../../utils/yaml-loader'
describe('Feature Name', () => {
let fixture: any
beforeEach(() => {
fixture = loadFixture()
})
it('should validate behavior', () => {
expect(fixture.property).toBe('expected')
})
})
Best practices:
- Use descriptive test names that explain what is being tested
- Group related tests using
describeblocks - Use
beforeEachfor fixture setup - Mock external dependencies (API calls, K8s API)
- Test error cases as well as success paths
- Keep tests focused — one assertion per test is ideal
Troubleshooting
Tests fail to load — Ensure test files are in __tests__ directories and end with .test.ts.
Import errors — Run npm install to ensure dependencies are installed.
YAML parsing issues — Validate YAML syntax and ensure the yaml-loader utility can handle the structure.
Timeout errors — Increase timeout in vitest config if needed:
export default defineConfig({
test: {
testTimeout: 10000, // 10 seconds
hookTimeout: 10000,
},
})
CI/CD Integration
Tests run automatically in CI pipelines:
npm run lint # Lint TypeScript code
npm run typecheck # Type checking
npm test # Run all tests
Test Maintenance
Adding Tests for a New MCP Server
- Create
__tests__directory:mcp-servers/your-server/__tests__/ - Create test files following the pattern:
your-server.config.test.tsyour-server.api.test.ts(if applicable)your-server.mcp.test.tsyour-server.k8s.test.ts(or.statefulset.test.ts)
- Add npm script:
"test:your-server": "vitest run your-server/__tests__"
Updating Tests After CRD Changes
When CRD specifications change, update corresponding *.config.test.ts files to validate new fields and structure.
Documentation
- Architecture — System architecture
- CRD Specifications — CRD definitions
License
Part of the Clerum project.