Tvinejs

What tvinejs does

tvinejs provides a full-stack TypeScript application structure centered on agent access. Projects use a Warp backend and a Weft frontend built with Next.js and React, with the backend handling routing, typed API access, authentication, sessions, ORM operations, migrations, administration, background tasks, caching, email, audit logging, and middleware.

The framework presents the same application to browsers and AI agents. Normal page URLs can return Markdown or JSON representations, while the /mcp endpoint exposes the app through Model Context Protocol. Actions defined in an application become typed MCP tools, allowing an agent to use application operations without reproducing browser interactions.

How it works

An agent discovers the application through /llms.txt, /.well-known/mcp.json, and /.well-known/tvine.json. It connects to /mcp over Streamable HTTP, lists available tools, and normally starts with read_page using the Markdown view. The response provides page content and control identifiers that can be passed to ui or related operations.

The default mode runs against a server-side session. For workflows requiring a person's existing login, an agent can call request_control; the person approves from their own browser tab, after which the agent can read and operate that visible tab. The person can stop the connection, and the agent can call release to return control.

Applications also expose /tvine/manifest for action and parameter information. Without an MCP client, an agent can request a page with Accept: text/markdown or x-tvine: 1, retaining the session identifier returned by the first response.

Setup and configuration

The project requires Node.js 22.15 or newer and pnpm 9. A new application can be scaffolded with:

npx tvinejs startproject my-app
cd my-app
pnpm exec tvine migrate
pnpm exec tvine createsuperuser
pnpm exec tvine dev

The development server runs on port 3000 by default, with administration at /admin and MCP at /mcp. The package is installed from npm as tvinejs, while its command and import-facing name is tvine; the documented alias form is npm install tvine@npm:tvinejs. Projects can also use pnpm exec tvine, or install the package globally when the command is needed outside a project.

Claude Code can connect through an .mcp.json entry using an HTTP URL such as http://localhost:4400/mcp. The tutorial setup demonstrates TVINE_SUPERUSER_USERNAME, TVINE_SUPERUSER_EMAIL, and TVINE_SUPERUSER_PASSWORD for noninteractive superuser creation.

Tools and capabilities

The built-in MCP tools include:

• read_page for Markdown or compact JSON page representations.
• expand for retrieving a complete section, such as all rows in a list.
• ui for clicks, field entry, and selection operations, with up to 20 steps in one call.
• do for invoking an action by identifier with parameters.
• request_control and release for consent-based browser-tab control.
• Application-specific typed tools generated from the actions defined by the project.

Tab control displays the agent's activity to the person and requires approval. Actions marked humanOnly remain unavailable to agents, while actions requiring confirmation continue to ask the person. Shield provides request scoring, bot challenges, blocking, rules, country rules, sandboxed JavaScript rules, and an analytics panel.

Limitations and notes

The server-side MCP mode uses its own session, so it is anonymous until the agent authenticates or supplies a token. Browser-tab control depends on the person approving access in their open tab and can be ended by either side. Refused requests use JSON responses with hints such as challenge_required, blocked, or rate_limited; the project recommends an honest User-Agent for agent traffic. Tvine applications run as one Node process combining the frontend and backend services.