@Uselink/

Model Context Protocol (MCP) server for uselink. Lets Claude, Cursor, Codex, and other MCP-aware AI tools publish HTML/Markdown docs, upload assets, and reply to stakeholder comments directly from the editor — no manual copy-paste, no portal switch.

Status: 0.2.0 — adds project + folder management and document moves.

---

Two ways to connect

Uselink supports two parallel authentication paths. Pick one — they don't overlap.

Option A — stdio + Personal Access Token (this package)

Best for CI/CD pipelines, scripted workflows, and power users who want fine-grained, revocable tokens.

claude mcp add uselink npx -y @uselink/mcp

Then set USELINK_API_KEY=ulk_pat_xxx in the Claude Code MCP environment. Full tool catalog (documents, projects, folders, webhooks orchestration) — everything below.

Option B — HTTP + OAuth (browser login, no token paste)

Best for non-technical users (PM, designers) and tools that mandate OAuth (Claude.ai Connectors, Cursor extension store).

claude mcp add --transport http uselink <USELINK_BACKEND_URL>/mcp

Browser opens, you log in to uselink, click "Allow" on the consent screen, done. Token rotation and revocation are automatic. Manage authorized clients at uselink → Settings → Connected Apps.

Tool coverage on HTTP transport is currently the document + asset + comment surface (14 tools). Project and folder tools remain stdio-only until they are wired into the HTTP server.

Both paths talk to the same backend; revoking via Settings → Connected Apps does not affect PATs, and rotating a PAT does not affect OAuth-issued tokens.

---

Install (Option A)

npm install -g @uselink/mcp

Or run on demand without a global install:

npx -y @uselink/mcp

Environment (Option A)

Variable	Required	Default	Notes
USELINK_API_KEY	Yes	—	Personal access token from uselink → Settings → Developer. Format: ulk_pat_xxx.
USELINK_API_BASE	No	uselink production backend	Override for self-hosted or staging environments.

---

Tools

Read tools

Tool	Description
uselink_list_documents	List documents in a workspace
uselink_read_document	Read full document content by ID
uselink_search_documents	Full-text search across a workspace
uselink_list_comments	List threaded comments on a document
uselink_list_assets	List assets attached to a document

Write tools

Tool	Description
uselink_create_document	Create a new document. Pass project_id and/or folder_id to drop it in a specific location
uselink_update_document	Update title, content, or format (slug is immutable)
uselink_move_document	Move a document into a different project / folder
uselink_publish_document	Publish a document (makes it publicly accessible)
uselink_unpublish_document	Unpublish a document
uselink_delete_document	Delete a document
uselink_upload_asset	Upload an image or file from local disk
uselink_upload_zip	Upload a zip archive; server extracts and stores each file
uselink_reply_comment	Reply to an existing comment thread
uselink_resolve_comment	Mark a comment thread as resolved

Project tools

Require projects:read (list/read/check-slug) or projects:write (everything else) on the PAT. Stdio + PAT only — not yet on HTTP transport.

Tool	Description
uselink_list_projects	List projects the PAT can see
uselink_read_project	Read a project by id
uselink_create_project	Create a project (workspace inferred from PAT)
uselink_update_project	Update name / slug
uselink_archive_project	Soft-archive a project
uselink_unarchive_project	Restore an archived project
uselink_rename_project_slug	Rename a project's slug
uselink_check_project_slug	Check whether a slug is available
uselink_set_default_project	Mark a project as the user's default
uselink_move_project_to_workspace	Move a personal project into a workspace
uselink_remove_project_from_workspace	Move a project back to personal

Folder tools

Require folders:read (list/read) or folders:write (everything else) on the PAT. Stdio + PAT only — not yet on HTTP transport.

Tool	Description
uselink_list_folders	List folders in a project (or under a parent folder)
uselink_read_folder	Read a folder by id
uselink_create_folder	Create a folder inside a project
uselink_update_folder	Update name / slug / color
uselink_move_folder	Re-parent a folder
uselink_delete_folder	Delete a folder (docs inside are moved to the project root)

Account tools

Require account:write on the PAT.

Tool	Description
uselink_set_url_handle	Set the user's public URL handle (3-30 lowercase letters/digits/hyphens, no leading/trailing hyphen). Required once before publishing the first document. Call this when publish returns USERNAME_REQUIRED.

Orchestrator

Tool	Description
uselink_publish_with_assets	Upload local images, rewrite <img src> to CDN URLs, create document, and publish — in one call

---

OAuth scopes (Option B only)

When you connect via HTTP transport, the consent screen lists these scopes:

Scope	Grants
docs:read	List, read, and search your documents
docs:write	Create, update, publish, unpublish, and delete documents
assets:write	Upload images and files to your documents
comments:read	Read comments on your documents
comments:moderate	Reply to and resolve comments on your documents
account:write	Set your public URL handle (required to publish your first doc)

Authorized clients can be listed and revoked individually at uselink → Settings → Connected Apps.

---

Development

npm install
npm run build      # compile to dist/
npm run dev        # run via tsx
npm run smoke      # local smoke test (lists tools)

Publishing

This package publishes from CI on tags matching mcp-v*.*.* via .github/workflows/publish-mcp.yml.

Prerequisite (one-time, manual): the @uselink npm organization must be reserved on npmjs.com and the NPM_TOKEN secret added to the GitHub repo before the first publish.

License

MIT