# Context Mapping Guide
This guide explains how to map your ContextVM services to MCP tools.
## Overview
The bridge translates between two protocols:
- **MCP (Model Context Protocol)**: Used by LLMs
- **DVM (Data Vending Machine)**: Used by ContextVM
## Context Structure
Each context represents a ContextVM service:
```json
{
"id": "unique_context_id",
"name": "Human-readable name",
"namespace": "nostr-namespace",
"jobRequestKind": 5051,
"jobResultKind": 6051,
"rootEntity": { ... },
"queries": { ... }
}
```
## Root Entity
The root entity defines the main process:
```json
{
"type": "entity-type",
"initialState": "initial-state",
"schema": {
"field1": {
"type": "string",
"description": "Field description",
"maxLength": 100
},
"field2": {
"type": "number",
"minimum": 0
}
},
"required": ["field1"],
"transitions": [ ... ]
}
```
### Field Types
Supported JSON Schema types:
- `string`: Text fields
- `number`: Numeric fields
- `integer`: Integer numbers
- `boolean`: True/false
- `array`: Lists
- `object`: Nested objects
### Field Constraints
- `minimum`, `maximum`: Numeric bounds
- `minLength`, `maxLength`: String length
- `pattern`: Regex validation
- `enum`: Allowed values
- `format`: Special formats (date, email, uri, etc.)
## Transitions
Transitions define state changes:
```json
{
"name": "transition_name",
"description": "What this transition does",
"from": "source-state",
"to": "target-state",
"inputSchema": {
"field": {
"type": "string",
"description": "Additional data needed"
}
}
}
```
### Generated MCP Tools
For each transition, a tool is created:
- **Name**: `{context_id}_{transition_name}`
- **Description**: From transition description
- **Parameters**: `token_id` + fields from `inputSchema`
## Queries
Configure read-only operations:
```json
{
"queries": {
"enabled": true,
"apiEndpoint": "https://api.example.com",
"cacheEnabled": true,
"cacheTTL": 300
}
}
```
This creates a `{context_id}_query` tool.
## Complete Example
```json
{
"id": "invoicing",
"name": "Invoicing System",
"namespace": "company.invoicing",
"jobRequestKind": 5055,
"jobResultKind": 6055,
"rootEntity": {
"type": "invoice",
"initialState": "draft",
"schema": {
"customer": {
"type": "string",
"description": "Customer name"
},
"amount": {
"type": "number",
"description": "Invoice amount",
"minimum": 0
},
"items": {
"type": "array",
"description": "Invoice line items",
"items": {
"type": "object",
"properties": {
"description": { "type": "string" },
"quantity": { "type": "number" },
"price": { "type": "number" }
}
}
}
},
"required": ["customer", "amount"],
"transitions": [
{
"name": "approve",
"description": "Approve invoice for sending",
"from": "draft",
"to": "approved",
"inputSchema": {
"approver_email": {
"type": "string",
"format": "email",
"description": "Email of approver"
}
}
},
{
"name": "send",
"description": "Send invoice to customer",
"from": "approved",
"to": "sent",
"inputSchema": {}
},
{
"name": "mark_paid",
"description": "Mark invoice as paid",
"from": "sent",
"to": "paid",
"inputSchema": {
"payment_reference": {
"type": "string",
"description": "Payment reference number"
},
"payment_date": {
"type": "string",
"format": "date",
"description": "Date payment was received"
}
}
}
]
},
"queries": {
"enabled": true,
"apiEndpoint": "https://api.invoicing.example.com",
"cacheEnabled": true,
"cacheTTL": 600
}
}
```
## Generated Tools
From the example above, these tools would be created:
1. **invoicing_create**: Create new invoice
2. **invoicing_approve**: Approve draft invoice
3. **invoicing_send**: Send approved invoice
4. **invoicing_mark_paid**: Mark invoice as paid
5. **invoicing_query**: Query invoice state
## Best Practices
1. **Clear Descriptions**: LLMs read these - be specific
2. **Validation**: Use JSON Schema constraints
3. **Required Fields**: Mark mandatory fields
4. **Logical Flow**: Design state transitions carefully
5. **Error Messages**: Provide helpful error descriptions
## Testing Your Mapping
```bash
# Start bridge in dev mode
npm run dev
# Check generated tools
curl http://localhost:4000/health
# Use MCP client to test
# (see main README for examples)
```
## Troubleshooting
### Tool Not Appearing
- Check `id` is unique
- Verify `namespace` matches ContextVM
- Ensure `jobRequestKind` is correct
### Validation Failing
- Check JSON Schema syntax
- Verify required fields are present
- Test regex patterns
### Transitions Not Working
- Verify `from`/`to` states exist
- Check state flow is logical
- Ensure ContextVM FSM matches
## Advanced Topics
### Multi-Step Workflows
Chain multiple transitions:
```
draft → review → approved → sent → paid
```
### Conditional Transitions
Use inputSchema to control flow:
```json
{
"inputSchema": {
"action": {
"type": "string",
"enum": ["approve", "reject"],
"description": "Approval decision"
}
}
}
```
### Nested Objects
Complex data structures:
```json
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"country": { "type": "string" }
},
"required": ["city", "country"]
}
}
```
