agenterra-0.1.3 is not a library.

🚀 Agenterra: Model Context Protocol Generator

Generate production-ready MCP (Model Context Protocol) servers and clients from OpenAPI specs with minimal configuration.

Agenterra transforms your OpenAPI specifications into fully-functional MCP servers and clients with type-safe Rust code, ready for integration with AI tools and workflows. Perfect for:

AI/ML Engineers 🤖 - Quickly expose APIs for LLM tool use
API Developers 🛠️ - Generate production-ready MCP servers from existing OpenAPI specs
FinTech & Data Teams 📊 - Build compliant financial data APIs with built-in validation
Startups & Enterprises 🚀 - Accelerate development of AI-powered applications

✨ Features

⚡ Blazing Fast - Built with Rust for maximum performance and safety
🔌 OpenAPI 3.0+ Support - Seamless integration with existing API specifications
🦀 Type-Safe Rust - Generate idiomatic, production-ready Rust code
🎨 Template-Based - Customize every aspect with Tera templates
🔍 Built-in Validation - Automatic OpenAPI schema validation
🚀 Production Ready - Includes logging, error handling, and configuration out of the box
🔌 MCP Protocol Support - Full compatibility with Model Context Protocol
💾 SQLite Resource Caching - Built-in resource caching with connection pooling for MCP clients
📦 Binary Distribution - Easy installation and deployment

🚀 Quick Start

Prerequisites

Rust 1.86.0+

Method 1: Build & Run from Source

# Clone the repository
git clone https://github.com/clafollett/agenterra.git
cd agenterra

# Generate MCP server from a local file without install:
cargo run -- scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io

# Generate MCP server from a remote URL without install:
cargo run -- scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote

# Generate MCP client without install:
cargo run -- scaffold mcp client --project-name petstore-client

# Or install the CLI
cargo install --path .

# Generate your MCP server from a local file
agenterra scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io

# Generate MCP server from a remote URL
agenterra scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote

# Generate MCP client
agenterra scaffold mcp client --project-name petstore-client

Note: After the single-crate refactor, you can now install directly from the project root with cargo install --path .

Method 2: Install from Git

# Install latest version
cargo install --git https://github.com/clafollett/agenterra.git agenterra

# Install specific version. Example: v0.1.0
cargo install --git https://github.com/clafollett/agenterra.git --tag v<VERSION> agenterra

Method 3: From Pre-built Binary (Coming soon)

Download the latest release for your platform from Releases

Make it executable and run:

chmod +x agenterra

# Generate your MCP server from a local file
./agenterra scaffold mcp server --schema-path ./tests/fixtures/openapi/petstore.openapi.v3.json --project-name petstore-server --base-url https://petstore3.swagger.io

# Generate MCP server from a remote URL
./agenterra scaffold mcp server --schema-path https://petstore3.swagger.io/api/v3/openapi.json --project-name petstore-remote

# Generate MCP client
./agenterra scaffold mcp client --project-name petstore-client

🔌 Integrating with MCP Clients

VS Code Integration

Add this to your VS Code settings (File > Preferences > Settings > Open Settings JSON):

{
  "mcp": {
    "servers": {
      "petstore": {
        "command": "cargo",
        "args": ["run", "--manifest-path", "/path/to/petstore-server/Cargo.toml"]
      }
    }
  }
}

Cursor Integration

Add this to your Cursor settings (File > Preferences > Settings > Extensions > MCP):

{
  "mcpServers": {
    "petstore": {
      "command": "cargo",
      "args": ["run", "--manifest-path", "/path/to/petstore-server/Cargo.toml"]
    }
  }
}

🕵️‍♂️ Testing with MCP Inspector

Test your MCP server with the MCP Inspector:

# Run directly with npx
npx @modelcontextprotocol/inspector cargo run --manifest-path=/path/to/petstore-server/Cargo.toml

# Or install globally
npm install -g @modelcontextprotocol/inspector
modelcontextprotocol-inspector cargo run --manifest-path=/path/to/petstore-server/Cargo.toml

⚡ Best Practices

Agenterra is designed to scaffold a well-structured MCP servers from OpenAPI specs. This is a great starting point, not necessarily a Best Practice. Wrapping an OpenAPI spec under an MCP facade is convenient, but not always the “proper” way to build MCPs. For robust, agent-friendly tools, consider how your server can best expose business logic, aggregate data, and provide clear, useful tool contracts.

Considerations:

Treat the generated code as a foundation to extend and customize.
Don't assume a 1:1 mapping of OpenAPI endpoints to MCP tools is ideal; you may want to aggregate multiple API calls into a single tool, or refactor handlers for advanced logic.
Use the scaffold to rapidly stub out endpoints, then iterate and enhance as needed.

🤔 Why Agenterra?

Postman now offers robust support for the Model Context Protocol (MCP), including:

MCP client and server features
Code generation
A catalog of hosted, discoverable MCP endpoints
Visual agent-building and cloud collaboration

When should you use Agenterra?

Offline, air-gapped, or regulated environments where cloud-based tools aren’t an option
Rust-first, codegen-centric workflows: Generate type-safe, production-grade Rust MCP servers from OpenAPI specs, ready for CI/CD and self-hosting
Full template control: Tweak every line of generated code, use custom templates, and integrate with your own infra
CLI-first automation: Perfect for embedding in build scripts and automated workflows

When should you use Postman?

Visual design, rapid prototyping, and cloud collaboration
Building, testing, and deploying MCP agents with a GUI
Discovering and consuming public MCP endpoints

Summary:

Use Postman for visual, collaborative, and cloud-first agent development
Use Agenterra for local, reproducible, code-first MCP server generation with maximum control and zero cloud dependencies

🏛️ Architecture

Agenterra is built for extensibility, automation, and code quality. Here’s how the core pieces fit together:

Core Modules:

openapi: Loads and validates OpenAPI specs (YAML/JSON, local or URL)
generator: Orchestrates code generation from the parsed OpenAPI model
template: Handles Tera-based templates for idiomatic Rust code
cli: Command-line interface for scaffolding, configuration, and workflow

Code Generation Flow:

OpenAPI Spec (local file or URL)
         │
         ▼
   [openapi module]
         │
         ▼
   [generator module]
         │
         ▼
   [template module]
         │
         ▼
Generated Rust MCP Server (Axum, etc.)

The generated server uses Stdio as the primary MCP protocol for agent integration, but can be extended for HTTP/SSE and other transports.
All code is idiomatic Rust, ready for further customization and production deployment.

💾 Resource Caching

Generated MCP clients include a sophisticated SQLite-powered resource caching system:

Features:

Connection Pooling - r2d2 connection pool for concurrent access
Character Encoding - Automatic charset detection from HTTP headers
TTL Support - Configurable time-to-live for cache entries
Analytics - Built-in cache hit/miss tracking and performance metrics
ACID Transactions - Database integrity with rollback support
Auto-cleanup - Configurable expired resource cleanup

Configuration Options:

let config = CacheConfig {
    database_path: "cache.db".to_string(),
    default_ttl: Duration::from_secs(3600),
    max_size_mb: 100,
    pool_max_connections: Some(10),
    pool_max_lifetime: Some(Duration::from_secs(300)),
    auto_cleanup: true,
    ..Default::default()
};

🤝 Contributing

We welcome contributions from the community! To keep Agenterra high-quality and maintainable, please follow these guidelines:

Fork & Clone: Fork the repo and clone your fork locally.
Branch Naming: Use the convention <type>/issue-<number>/<description> (e.g., docs/issue-57/update-readme).
Pull Requests:
- All PRs require review.
- All tests must pass (cargo test and integration tests).
- Code coverage must not decrease.
- Update documentation for any user-facing or API changes.
Testing:
- Add or update unit and integration tests for all new features or bugfixes.
- Run: cargo test --test e2e_mcp_test
Docs:
- Update relevant docs and add examples for new features.
- Document any new patterns or conventions.
CI/CD:
- Ensure your branch passes all checks before requesting review.

For more details, see CONTRIBUTING.md if available.

🛠️ Developer Workflow

Here’s how to work productively with Agenterra as a contributor or advanced user:

🧪 Running Tests

Unit & Integration Tests:
- Run all tests: cargo test
- Run integration tests (all templates with OpenAPI specs):
```
cargo test --test e2e_mcp_test
```
Test Location: See tests/e2e_mcp_test.rs for integration coverage.
Test-First Principle: Add failing tests before implementing new features or bugfixes.

🏗️ Building

Standard build:
```
cargo build --release
```

🧩 Custom Templates

See docs/TEMPLATES.md for template development
Add templates under templates/ directory

🏗️ Generated Project Structure

petstore-server/
├── Cargo.toml          # Rust project manifest
├── src/
│   ├── mcp/            # MCP protocol implementation
│   │   ├── mod.rs       # MCP server implementation
│   │   └── handlers/    # MCP request handlers
│   ├── api/             # Generated API code
│   │   ├── mod.rs       # API module exports
│   │   ├── models/      # Generated data models
│   │   └── operations/  # API operation handlers
│   ├── config.rs        # Server configuration
│   ├── error.rs         # Error handling
│   └── main.rs          # MCP server entry point
├── .env                # Environment variables
└── README.md           # Project documentation

📚 Examples & Configuration

Basic Example: Petstore API

# Download the Petstore OpenAPI spec
curl -o petstore.json https://petstore3.swagger.io/api/v3/openapi.json

# Generate the MCP server
agenterra scaffold mcp server --schema-path petstore.json --project-name petstore-server

# Generate the MCP client
agenterra scaffold mcp client --project-name petstore-client

# Build and run the server
cd petstore-server
cargo run

Configuration Options

Agenterra is configured through command-line arguments. By default, projects are created in the current directory (like cargo new):

# Generate MCP server (creates ./my_server/)
agenterra scaffold mcp server --schema-path your_api.json --project-name my_server

# Generate MCP client (creates ./my_client/)
agenterra scaffold mcp client --project-name my_client

# Specify a parent directory with --output-dir
agenterra scaffold mcp server --schema-path api.json --project-name my_server --output-dir ~/projects
# Creates: ~/projects/my_server/

Environment Variables:

AGENTERRA_OUTPUT_DIR - Default parent directory for generated projects
AGENTERRA_TEMPLATE_DIR - Custom template directory location

Templates

Agenterra uses Tera templates for code generation.

Built-in Server Templates:

rust_axum - Rust MCP server using Axum web framework

Built-in Client Templates:

rust_reqwest - Rust MCP client with REPL interface and SQLite resource caching

Custom Templates:

Create templates under templates/mcp/server/ or templates/mcp/client/
Details: See docs/TEMPLATES.md

📄 License

MIT License - see LICENSE for details.

🔗 Related Projects

MCP Protocol - Model Context Protocol specification
RMCP - Rust MCP implementation
Axum - Web framework for Rust
Tera - Template engine for Rust

agenterra 0.1.3