hyperterse

---

Hyperterse is an agentic server framework: one build ships agents (A2A), tools (MCP), prompts, resources, database adapters, auth, caching, and observability from a single process. You declare surfaces in config; the compiler validates and bundles them. Clients use MCP Streamable HTTP at /mcp for tools, prompts, and resources; A2A-style agent routes live at /agent/{name} when you define agents.

Where to start

• Agents — Declarative agents and A2A: Agents overview, Agents quickstart.
• Tools — Callable MCP tools (DB or scripts): Tools, Scripts, Adapters.
• Resources — Static context for clients: Resources.
• Prompts — Reusable prompt templates: Prompts.

The Quickstart walks through install, scaffold, and run, then optional MCP tool checks.

What Hyperterse is for

• Running agents alongside MCP tools, prompts, and resources in one deployable service
• Exposing database queries and custom logic as MCP tools with declarative config
• Production Streamable HTTP for MCP and A2A routes for agents
• TypeScript handlers and transforms where config alone is not enough

Core capabilities

• Agents: declarative configs, tool-access policies, multi-provider models, per-agent A2A HTTP.
• Filesystem discovery: one MCP tool per tool definition; prompts and resources follow the same discover-and-compile model (see Project structure).
• Execution models: DB-backed tools (use + statement) or script-backed tools (handler).
• Database adapters: PostgreSQL, MySQL, SQLite, 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.

Quick Start

Install

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

Initialize

hyperterse init

Generated starter structure:

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

Start

hyperterse start

With live reload:

hyperterse start --watch

Verify health

curl http://localhost:8080/heartbeat

Expected response:

{ "success": true }

Optional: list MCP tools

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

Optional: discover project tools (search)

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.

Execute a project tool

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

Validate and build

hyperterse validate
hyperterse build -o dist
hyperterse serve dist/

Configuration model

Project layout

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

Root config (.hyperterse)

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

Tool Examples

DB-backed tool

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 }}"

Script-backed tool

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)

Runtime model

MCP — Streamable HTTP at /mcp (JSON-RPC 2.0): tools, prompts, resources, completion, subscriptions. See MCP transport.

A2A — JSON-RPC per agent at /agent/{agentName} (agent card, messaging, tasks, streaming). See A2A transport and Agents.

Execution pipeline:

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

MCP spec compliance

Hyperterse implements the Model Context Protocol (MCP) specification 2025-11-25.

Compliance status by component:

Spec component	Status
Base protocol (JSON-RPC 2.0)	✅
Lifecycle (initialize/initialized)	✅
Tools (list, call, listChanged)	✅
Resources (list, read, subscribe, updated)	✅
Prompts (list, get, listChanged)	✅
Completion (ref/prompt, ref/resource)	✅
Pagination (cursor/nextCursor)	⚠️
Tool result content types (image, audio, resource_link)	⚠️

Text content for tool results is supported; image, audio, and resource links are optional. Pagination applies when tools, prompts, or resources exceed typical small-to-medium counts.

Security notes

• 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 map

• Documentation index (llms.txt)
• Introduction
• Quickstart
• Project structure
• Agents — Overview, Agents quickstart, Tool access, Runtime API, Model providers
• Tools — Tools, Scripts, Adapters
• Resources — Resources
• Prompts — Prompts
• Authentication
• MCP transport
• A2A transport
• Execution pipeline
• CLI reference
• Agent config, Prompt config, Resource config
• Configuration schemas

Contributing

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.

---