Project structure

Hyperterse uses the filesystem as the source of truth. You define database connections, tools, prompts, and resources in role-based directories. File and directory names become identifiers. The framework discovers everything from project structure — you never register runtime entities manually.

​

Directory layout

A typical project looks like this:

​

Root configuration

The .hyperterse file contains service-level settings: name, version, server port, log level, cache defaults, build options, and discovery settings for role directories. Adapter and tool definitions live in app/. Prompts and resources can be discovered from app/ or defined inline using root arrays (prompts, resources, resource_templates). When you run hyperterse start or hyperterse build without arguments, the CLI looks for .hyperterse in the current directory. See Root configuration reference for the complete field specification.

​

Adapter discovery

The compiler scans app/adapters/*.terse at build time. Each file defines exactly one adapter. The filename (without extension) becomes the adapter’s identifier, unless the file explicitly sets a name field. See Adapters for how adapters work, and Adapter configuration reference for the field specification.

​

Tool discovery

The compiler scans app/tools/*/config.terse at build time. Each config.terse file defines one MCP tool. The directory name becomes the tool name, unless the file explicitly sets a name field. Every tool must define either a database connection (use) or a handler script (handler). Tools with neither are rejected during validation. See Tools for execution models, and Tool configuration reference for the field specification.

​

Prompt discovery

The compiler scans app/prompts/**/*.terse at build time. Each file defines one MCP prompt. The filename becomes the prompt name unless an explicit name is set. See Prompts and Prompt configuration reference.

​

Resource discovery

The compiler scans app/resources/**/config.terse at build time. Each resource folder defines one concrete resource (uri) or one resource template (uri_template), with optional content files colocated in the same folder. See Resources and Resource configuration reference.

​

Script resolution

Script paths in tool configs are resolved relative to the tool directory. You can declare them explicitly, or rely on convention-based discovery. Common conventions include handler.ts, input.ts, and output.ts. See Scripts for the full script model.

​

Vendor dependencies

If your tool scripts import npm packages, add a package.json at the project root and install your dependencies. Build output includes everything needed to run scripts, so deployment does not depend on node_modules/ being present.