Twinlens MCP Server

twinlens

A lens is a public AI page that answers questions from its owner's own material, with citations. twinlens is a small forwarding client for the hosted lens service: it creates a lens from a profile, adds knowledge to an unclaimed lens, and reports how ingestion is going.

Creation is anonymous by default — no account, no token. An anonymously created lens is live immediately at its share URL, can be claimed afterwards through its claim URL, and expires after 30 days if it never is. If you do have an account, setting MINDOLA_SESSION_TOKEN sends it as a Bearer token and the lens is created directly under that account. The endpoint can be overridden with MINDOLA_MCP_URL (default https://app.mindola.ai/mcp/lens).

Creation etiquette (part of the contract): summarize the proposed profile and get the user's explicit confirmation before calling create, and only include information the user provided or confirmed. Never fill a profile with guesses.

CLI

npx @reneturcios/twinlens create '{"displayName":"Ada Example","tone":"warm","facts":["Works on compilers"]}'
npx @reneturcios/twinlens add-knowledge '{"lens_token":"abc123","items":[{"type":"text","content":"A note","title":"Note"}]}'
npx @reneturcios/twinlens status abc123
npx @reneturcios/twinlens --version

create takes the profile as one JSON object (every field optional). add-knowledge takes {lens_token, items} the same way. status takes the share token (the part of the share URL after /me/) directly.

Exit codes: 0 on success, 1 on a runtime error (including an upstream rejection, e.g. adding knowledge to a claimed lens), 2 on a usage error.

MCP server

npx -y @reneturcios/twinlens mcp

MCP client config:

{
  "mcpServers": {
    "twinlens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/twinlens", "mcp"]
    }
  }
}

Tools

• create_digital_twin_lens — Create a lens from a user-confirmed profile. All fields optional: displayName (≤80 chars), tagline, bio, context, audience (≤500 chars), sourceSummary, topicName (≤80 chars), locale (BCP-47), tone (warm | neutral | professional | playful), accentColor, expertise (string[]), boundaries (string[]), facts (string[], ≤30), suggestedPrompts (string[], ≤4), vibeWords (string[], ≤4). Read the result from structuredContent: shareUrl, claimUrl, manageUrl, claimRequired, expiresAt, factCount.
• add_lens_knowledge — Add up to 20 items to an unclaimed lens. lens_token (string, required), items (required): each {type: "text" | "url", content (≤20000 chars), title? (≤80 chars)}. Items ingest in the background.
• get_lens_status — lens_token (string, required). Reports claimed and knowledge totals (total, ready, pending, failed); poll with it after adding knowledge until pending reaches zero.

Docker

docker run -i ghcr.io/cloudcorprecords/twinlens
docker run --rm ghcr.io/cloudcorprecords/twinlens status abc123

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios