Mini App MCP

mini-app-mcp

Agent-First CRUD store MCP server — schema.yaml driven, SQLite backend, multi-table in a single daemon.

What it does

mini-app-mcp is a lightweight MCP server that manages one or more SQLite tables in a single running process. The shape of each table is defined entirely by a schema.yaml file; no migrations, no REST API, no GUI. CRUD is exposed exclusively as MCP tools, making it a natural backend for agents that need structured persistent storage.

Design principles

• `schema.yaml` as sole schema authority — field names, types, and required constraints are read from YAML at startup. No field is hard-coded in application code.
• Multi-table in one daemon — a single server process discovers and mounts all tables found under the configured User and Project scope directories. A dedicated legacy mode (MINI_APP_SCHEMA + MINI_APP_DB) preserves the original single-table behaviour.
• MCP-only entry point — there is no HTTP/REST/CLI CRUD interface. All reads and writes go through MCP tools.
• Structured JSON errors — every error response carries a machine-readable code field so agents can handle failures programmatically.

schema.yaml format

table: issues

title: "Issue tracker" description: "Tracks bugs and feature requests for a project." fields:

• name: title type: string required: true description: "Short one-line summary of the issue."
• name: state type: string required: false
• name: tags type: array required: false

The optional title and description keys at the table level provide human- and AI-readable metadata about the table. Each field entry may also carry an optional description string. All three keys follow the OpenAPI 3.1 / JSON Schema 2020-12 naming convention and are included in info tool output and the schema://json resource.

Supported types: string, number, boolean, array, object.

Configuration

Multi-table mode (recommended)

Tables are discovered at startup by scanning both directories. Project-scope definitions take precedence over User-scope definitions for the same table name.

Legacy single-table mode

When MINI_APP_SCHEMA and MINI_APP_DB are set the server starts in legacy mode, mounting exactly one table. The table argument on all tools may be omitted in this mode.

All variables can also be placed in a .mini-app-mcp.env file in the working directory.

MCP tools

All tools accept an optional table argument that selects the target table. In multi-table mode the argument is required; omitting it returns error code TABLE_REQUIRED. Supplying an unknown table name returns error code TABLE_NOT_FOUND. In legacy single-table mode the argument may be omitted.

MCP resources

In addition to the tools above, the server exposes 7 read-only Resources addressable by URI. Resources are intended for agents that want to fetch the schema definition or reference documentation without invoking a mutating tool.

The info tool and schema://json resource return equivalent content but serve different purposes: info is a callable tool (good for one-off introspection in a conversation), while resources are URI-addressable and can be subscribed to or cached by the client.

Usage

Start the server via --mcp (stdio transport) or --mcp-http (streamable HTTP transport). These are the only entry points; there is no REST/CLI-CRUD surface.

Multi-table mode

Place each table's schema.yaml and .db under ~/.mini-app/ / (User scope) or ./.mini-app/ / (Project scope), then start without any extra environment variables:

mini-app-mcp --mcp

Register it once in .mcp.json to serve all mounted tables:

{

"mcpServers": { "mini-app": { "command": "mini-app-mcp", "args": ["--mcp"] } } }

Multi-device mode (streamable HTTP)

Run one central daemon that owns the SQLite files, and connect from any number of devices as remote MCP clients. Because every device talks to the same single process, the single-writer storage model is preserved — no cross-device sync or conflict handling exists or is needed.

# Central host — loopback (same-machine clients, e.g. behind an SSH tunnel)

mini-app-mcp --mcp-http # default bind 127.0.0.1:8484

Central host — LAN exposure requires a token (generate one once):

openssl rand -hex 32

MINI_APP_HTTP_TOKEN= mini-app-mcp --mcp-http --bind 0.0.0.0:8484

Client registration in .mcp.json (any device on the network):

{

"mcpServers": { "mini-app": { "type": "http", "url": "http://central-host:8484/mcp", "headers": { "Authorization": "Bearer " } } } }

Security model:

• Loopback bind (default): MINI_APP_HTTP_TOKEN is optional. The transport's built-in Host header validation (loopback-only) guards against DNS rebinding.
• Non-loopback bind: MINI_APP_HTTP_TOKEN must be set — startup is refused otherwise. Every request must then carry Authorization: Bearer .
• Transport encryption (TLS) and any richer authorization are intentionally out of scope; terminate TLS at a rev