mrapids 0.1.31

Your OpenAPI, but executable
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

# MCP Integration Implementation Summary

## Overview
Successfully implemented a comprehensive Model Context Protocol (MCP) integration for MicroRapid, enabling AI agents to safely execute API operations while maintaining security and auditability.

## Architecture: "Two Doors, One Engine"
- **Human Door**: CLI interface (`mrapids` command)
- **Agent Door**: MCP server interface (JSON-RPC protocol)
- **Shared Engine**: Core API layer with business logic

## Phase 1: Core API Module ✅
### Components Implemented:
- **Request/Response Types** (`src/core/api/types.rs`)
  - `RunRequest`, `ListRequest`, `ShowRequest` with JSON schemas
  - Comprehensive response types with proper serialization
  
- **Error Taxonomy** (`src/core/api/errors.rs`)
  - Machine-readable error codes (1xxx policy, 2xxx auth, etc.)
  - Structured error responses with context
  
- **API Operations** (`src/core/api/run.rs`, `list.rs`, `show.rs`)
  - Extracted business logic from CLI commands
  - No interactive prompts or I/O operations

## Phase 2: Policy Engine ✅
### Features:
- **Policy Model** (`src/core/policy/model.rs`)
  - YAML/TOML policy definitions
  - Rule-based access control with glob patterns
  - Conditional policies based on method, tags, time
  
- **Pattern Matching** (`src/core/policy/engine.rs`)
  - Pre-compiled glob patterns for performance
  - Efficient evaluation with early termination
  - Decision explanation for debugging
  
- **Testing Framework** (`src/core/policy/tests.rs`)
  - Policy validation and linting
  - Coverage analysis
  - Example policies for common scenarios

## Phase 3: MCP Server ✅
### Server Components:
- **Configuration System** (`agent/src/config.rs`)
  - TOML-based configuration
  - Environment variable support
  - Security controls (allow_override_env, allow_override_auth)
  
- **Audit Logging** (`agent/src/audit.rs`)
  - Structured audit entries with unique IDs
  - Log rotation by size and time
  - Compression of rotated logs
  - Configurable audit levels (none, basic, detailed)
  
- **Response Redaction** (`agent/src/redact.rs`)
  - Pattern-based secret detection
  - Redacts: API keys, JWTs, passwords, credit cards
  - Configurable custom patterns
  
- **Auth Management** (`agent/src/auth.rs`)
  - Profile-based authentication
  - Environment variable resolution
  - Never exposes actual secrets to agents
  
- **JSON-RPC Tools** (`agent/src/tools/`)
  - `list`: List available operations with filtering
  - `show`: Show operation details and schemas
  - `run`: Execute operations with policy enforcement

## Security Features
1. **Policy Enforcement**: All operations checked against configurable policies
2. **Audit Trail**: Complete logging of all agent actions
3. **Secret Protection**: Automatic redaction of sensitive data
4. **Auth Isolation**: Credentials never exposed to agent context
5. **Input Validation**: Schema validation for all requests

## Usage Example
```bash
# Generate example configuration
./target/debug/mrapids-agent --generate-config > mcp-server.toml

# Start the MCP server
./target/debug/mrapids-agent --config mcp-server.toml

# The server exposes JSON-RPC tools at http://localhost:8080
```

## Tool Schemas
- `/schemas/tools/list-tool.json`: List operations schema
- `/schemas/tools/show-tool.json`: Show operation details schema  
- `/schemas/tools/run-tool.json`: Execute operation schema

## Future Enhancements (Pending)
1. **Rust SDK Generation**: Add reqwest-based client generation
2. **Contract Testing**: Generate tests from OpenAPI specs
3. **Breaking Change Detection**: `mrapids diff` command
4. **Reference Debugging**: `mrapids explain` for $ref chains
5. **Agent Examples**: Integration examples for popular AI frameworks

## Key Design Decisions
1. **Separation of Concerns**: MCP server is a thin adapter over core API
2. **No Direct File Access**: Agents can't read/write files directly
3. **Structured Output**: All responses use JSON with schemas
4. **Fail-Safe Defaults**: Restrictive policies by default
5. **Observability First**: Comprehensive audit logging built-in

The implementation provides a secure, auditable, and extensible foundation for AI agents to interact with APIs through MicroRapid while maintaining the principle of least privilege.