# tvinejs [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/zohaib3249/tvine  
**GitHub Stars:** 0  
**npm Downloads (last month):** 2016  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tvinejs

## Description
Tvine: agent-native full-stack web framework. TypeScript backend (ORM, migrations, auth, admin, tasks, built-in MCP server) + Next.js/React frontend that AI agents can read and drive.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "tvinejs": {
    "command": "npx",
    "args": ["-y","tvinejs"]
  }
}
```

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/tvinejs/readme_