The declarative framework for performant MCP servers.
Website • Documentation • Quick Start • Examples • GitHub

Hyperterse is a tool-first MCP framework for building AI-ready backend surfaces from declarative config.

You define tools and adapters in the filesystem, and Hyperterse handles compile-time validation, script bundling, runtime execution, auth, caching, and observability.

• Exposing database queries and custom logic as MCP tools
• Running a production MCP server over Streamable HTTP
• Keeping tool definitions declarative while still supporting TypeScript handlers/transforms

• Filesystem discovery: each app/tools/*/config.terse becomes one project tool.
• Execution models: DB-backed tools (use + statement) or script-backed tools (handler).
• Database adapters: PostgreSQL, MySQL, MongoDB, Redis.
• Per-tool auth: built-in allow_all and api_key, plus custom plugins.
• In-memory caching: global defaults + per-tool overrides.
• Observability: OpenTelemetry tracing/metrics + structured logging.

curl -fsSL https://hyperterse.com/install | bash

hyperterse init

Generated starter structure:

.
├── .hyperterse
├── .agent/
│   └── skills/
│       └── hyperterse-docs/
│           └── SKILL.md
└── app/
    └── tools/
        └── hello-world/
            ├── config.terse
            └── handler.ts

hyperterse start

With live reload:

hyperterse start --watch

curl http://localhost:8080/heartbeat

Expected response:

{ "success": true }

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }' | jq

By design, Hyperterse exposes two transport-layer tools:

• search - discover project tools by natural language
• execute - execute a project tool by name

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "hello world greeting"
      }
    },
    "id": 2
  }' | jq

Search hits include name, description, relevance_score, and inputs.

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "execute",
      "arguments": {
        "tool": "hello-world",
        "inputs": { "name": "Hyperterse" }
      }
    },
    "id": 3
  }' | jq

hyperterse validate
hyperterse build -o dist
hyperterse serve dist/

my-project/
├── .hyperterse
├── app/
│   ├── adapters/
│   │   └── primary-db.terse
│   └── tools/
│       ├── get-user/
│       │   ├── config.terse
│       │   ├── input.ts
│       │   └── output.ts
│       └── get-weather/
│           ├── config.terse
│           └── handler.ts
└── package.json

name: my-service
server:
  port: 8080
  log_level: 3
tools:
  search:
    limit: 10
  cache:
    enabled: true
    ttl: 60

description: "Get user by ID"
use: primary-db
statement: |
  SELECT id, name, email
  FROM users
  WHERE id = {{ inputs.user_id }}
inputs:
  user_id:
    type: int
auth:
  plugin: api_key
  policy:
    value: "{{ env.API_KEY }}"

description: "Get weather by city"
handler: "./handler.ts"
inputs:
  city:
    type: string
auth:
  plugin: allow_all

Supported input types:

• string
• int
• float
• boolean
• datetime

Each tool must define exactly one execution mode:

• use (adapter-backed), or
• handler (script-backed)

All tool interaction happens through MCP Streamable HTTP at /mcp (JSON-RPC 2.0).

Execution pipeline:

1. Tool resolution
2. Authentication
3. Input transform (optional)
4. Execution (DB or handler)
5. Output transform (optional)
6. Response serialization

• Use {{ env.VAR_NAME }} for secrets and connection strings.
• {{ inputs.field }} statement substitution is textual; enforce strict input schemas and safe query patterns.
• Configure tool-level auth explicitly for production use.

• Documentation index (llms.txt)
• Introduction
• Quickstart
• Project structure
• Tools
• Adapters
• Scripts
• MCP transport
• Execution pipeline
• CLI reference
• Configuration schemas

1. Fork the repo.
2. Create a feature branch.
3. Add or update tests.
4. Run validation locally.
5. Open a PR.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

The declarative framework for performant MCP servers.
Website • GitHub • Documentation