tian-vue-annotate-server

Local HTTP API + MCP server for tian-vue-annotate. Lets AI coding agents (Claude Code, OpenCode) read, respond to, and resolve visual annotations directly from your running Vue app.

Install

npm install -g tian-vue-annotate-server

Quick start

# 1. In your project root — detects your agent and writes .mcp.json
tian-vue-annotate-server init

# 2. Start the HTTP + MCP server
tian-vue-annotate-server server
# → HTTP API on http://localhost:4848

Then in your Vue app (tian-vue-annotate):

<TianAnnotate sync-endpoint="http://localhost:4848" />

Vite users: use the Vite plugin instead — it embeds the API server directly and needs no separate process. See the tian-vue-annotate docs.

CLI commands

| Command | Description | | --- | --- | | tian-vue-annotate-server init | Detect agent, write .mcp.json and .tian-annotate/config.json | | tian-vue-annotate-server server | Start HTTP API server (port 4848) | | tian-vue-annotate-server mcp | Start MCP stdio server (used by AI agents — no HTTP bind) | | tian-vue-annotate-server doctor | Health check: HTTP reachability + DB status |

MCP setup

init writes .mcp.json automatically for the detected agent. To add manually:

Claude Code

claude mcp add tian-annotate -- tian-vue-annotate-server mcp

Or in .mcp.json:

{
  "mcpServers": {
    "tian-annotate": {
      "type": "stdio",
      "command": "tian-vue-annotate-server",
      "args": ["mcp"]
    }
  }
}

OpenCode

{
  "mcp": {
    "tian-annotate": {
      "type": "local",
      "command": ["tian-vue-annotate-server", "mcp"]
    }
  }
}

Note: server and mcp are separate processes by design. server owns the HTTP port; mcp is spawned by the agent per-session over stdio and never touches the HTTP port. Both share the same SQLite database (.data/store.db, WAL mode).

MCP tools

The agent has access to these tools after init:

| Tool | Description | | --- | --- | | tian_annotate_list_pending | List all pending annotations | | tian_annotate_get_annotation | Get full annotation details by ID (CSS, styles, component tree) | | tian_annotate_acknowledge | Mark annotation as acknowledged | | tian_annotate_resolve | Mark annotation as resolved | | tian_annotate_dismiss | Dismiss with a reason | | tian_annotate_reply | Add a reply to the annotation thread | | tian_annotate_watch | Block until a new annotation arrives (for event-driven loops) |

Environment variables

| Variable | Default | Description | | --- | --- | --- | | PORT | 4848 | HTTP server port | | ALLOWED_ORIGIN | * | CORS origin — restrict in production |

How it works

Browser (tian-vue-annotate)
  │  POST /api/annotations               → creates annotation in SQLite
  │  POST /api/annotations/:id/dispatch  → spawns Claude/OpenCode
  │
  └─ HTTP API (:4848)
       │
       └─ SQLite (.data/store.db, WAL)
            │
            └─ MCP server (stdio, per agent session)
                 tian_annotate_list_pending
                 tian_annotate_get_annotation
                 tian_annotate_resolve …

Agent workflow:

1. tian_annotate_watch — blocks until a new annotation arrives
2. tian_annotate_get_annotation — reads full context (element path, classes, Vue component chain, computed styles)
3. Agent locates and fixes the source file
4. tian_annotate_reply — posts a summary to the thread
5. tian_annotate_resolve — marks done (or tian_annotate_dismiss if it can't be fixed safely)

License

PolyForm Noncommercial 1.0.0 — free for personal and open-source use.