Use local ZajLibrary MCP

Learn · guide · Library MCP · local

TL;DR

Use zajlibrary-local at http://localhost:4321/api/mcp when you need the dev corpus or the dev feedback queue — not on every session. Start npm run dev from app/ (port 4321 only), register both servers in .mcp.json, and after doc edits run npm run build:index then restart dev.

For beginners and agents

Local MCP is optional. Default to zajlibrary (prod) for real deploys and stable citations. Switch to local only when the table in When to use local applies. Compare commitShaShort to local git HEAD only when you are working inside the ZajLibrary repo itself; from a consuming project, treat it as a freshness signal and prefer zajlibrary-local when the local docs are ahead of prod.

---

What you’ll learn

• When local beats prod (and when it does not)
• One-time setup — dev server, dual MCP wiring, env for feedback
• Index refresh after content changes
• Three workflows — doc authoring, CodeCanyon first walkthrough, feedback dry-run
• Verify and troubleshoot local MCP

---

Before you start

Requirement	Notes
ZajLibrary repo cloned	This guide assumes you can run dev from app/
Node 22+	Astro 6 requirement
MCP client	Cursor, Claude Code, or Streamable HTTP host
Feedback on local	app/.env.local with dev DATABASE_URL (Neon development branch)
Admin feedback tools	Optional MCP_ADMIN_TOKEN in app/.env.local + Bearer on MCP requests

Full prod + tool reference: Use the ZajLibrary MCP.

---

When to use local (not production)

Register both zajlibrary and zajlibrary-local in your MCP client. Pick per session:

Situation	Server
Real CodeCanyon deploy — shipping an app; stable playbook; handoff to others	zajlibrary (prod)
First-time walkthrough / QA — agent follows setup-new before you trust prod	zajlibrary-local
Authoring or enriching docs in this repo	zajlibrary-local
Testing submit_feedback → dev queue + /admin without polluting prod	zajlibrary-local
Unreleased playbook on dev not yet deployed	zajlibrary-local
Canonical URL in a PR, doc, or message to a teammate	zajlibrary (prod URLs)

After local validation, re-check critical steps against prod before you treat a deploy as production-truth.

---

Setup

1. Start the dev server

From app/ (port 4321 is locked — do not use another port):

cd app
npm run dev

Open http://localhost:4321. MCP endpoint: http://localhost:4321/api/mcp.

2. Wire both MCP servers

Cursor

Repo root .mcp.json:

{
  "mcpServers": {
    "zajlibrary": {
      "type": "http",
      "url": "https://library.zajapps.com/api/mcp"
    },
    "zajlibrary-local": {
      "type": "http",
      "url": "http://localhost:4321/api/mcp"
    }
  }
}

Reload MCP servers after editing. Disable or ignore zajlibrary-local when dev is not running (connection refused).

Claude Code

claude mcp add --transport http zajlibrary https://library.zajapps.com/api/mcp -s user
claude mcp add --transport http zajlibrary-local http://localhost:4321/api/mcp -s user
claude mcp list

3. Env for local feedback (optional but recommended for QA)

Create or extend app/.env.local (gitignored):

DATABASE_URL=postgresql://…   # Neon *development* branch
MCP_ADMIN_TOKEN=your-long-random-token   # optional — admin list/review tools

• submit_feedback works anonymously on local if DB is wired.
• list_feedback / review_feedback need Bearer MCP_ADMIN_TOKEN (or an allowlisted Better Auth session on :4321).

Triage UI: http://localhost:4321/admin.

---

How local MCP loads content

The corpus is not read from disk at request time. The server imports a build-time index (src/mcp/generated/docs.json) when dev starts.

flowchart LR
  Edit["Edit .md / .mdx"] --> BuildIndex["npm run build:index"]
  BuildIndex --> DocsJson["docs.json"]
  DocsJson --> Restart["Restart npm run dev"]
  Restart --> Mcp["/api/mcp"]
  Mcp --> Agent["zajlibrary-local client"]

Event	Index updates?
npm run dev start (predev)	Yes — regenerates index
Save a doc while dev runs	No — run build:index + restart
Prod deploy	Prod MCP updates after Vercel build

Index refresh loop

1. Save under app/src/content/docs/.
2. cd app && npm run build:index
3. Restart dev (stop + npm run dev, or fresh terminal).
4. list_contents — confirm totalDocs and commitShaShort match expectation.

---

Workflows

A. Authoring or enriching library docs

1. Dev on 4321 · MCP client on zajlibrary-local
2. search_library → get_document for the page you are editing
3. After saves: index refresh loop (above)
4. Before merge: spot-check the same page via prod if it is already deployed

B. First-time CodeCanyon setup-new walkthrough

Use when an agent (or you) follows Set up a New CodeCanyon App before trusting the live playbook.

1. Dev on 4321 · zajlibrary-local
2. Orient — list_contents (codecanyon / setup-new paths)
3. Read — get_document each phase; execute ## Steps + ## Checklist in order
4. Verify — command output for each checklist item
5. Feedback — gaps via submit_feedback (pageUrl, category, dedupeKey = <phase>/<step>)
6. Triage — http://localhost:4321/admin (dev queue only)
7. Promote — when satisfied, repeat critical reads on zajlibrary (prod)

Machine setup registration: Phase 1 · Machine setup §3.

C. Feedback dry-run (MCP + admin)

1. Local dev + dev DATABASE_URL
2. Agent calls submit_feedback with a test row (use a real pageUrl when possible)
3. Confirm row in /admin or via list_feedback with Bearer token
4. Optional: review_feedback to move through review states on dev

---

Verify

cd app
npm run test:mcp

Expected: connects to :4321, all six tools registered, read tools exercised.

Manual checks:

# inside the ZajLibrary repo only: commit on disk should match list_contents.commitShaShort (local)
git rev-parse --short HEAD

In the MCP client: list_contents → note totalDocs, commitShaShort, semanticEnabled.

---

Troubleshooting

Symptom	Fix
Connection refused on :4321	cd app && npm run dev — port 4321 only
New page missing from search	npm run build:index then restart dev
submit_feedback fails	Check dev DATABASE_URL in app/.env.local; run npm run feedback:schema if needed
Admin tools denied	Set MCP_ADMIN_TOKEN in .env.local; send Bearer on MCP requests; restart dev
Agent reads stale playbook	Wrong server — prod vs local; or index not refreshed
Local works, prod differs	Expected until you deploy — prod corpus updates on Vercel build

---

Checklist

• npm run dev running on 4321
• zajlibrary-local registered; prod still available for deploy sessions
• After doc edits: build:index + dev restart
• npm run test:mcp passes
• list_contents.commitShaShort matches local git when validating WIP inside the ZajLibrary repo; consuming projects treat it as freshness metadata
• Feedback QA uses dev DB; prod queue untouched until deploy
• Real deploy sessions use zajlibrary (prod)

---

See also

Use the ZajLibrary MCP Prod URL, all six tools, auth, smoke test, operator index/embed

Library MCP hub Topic home + quick reference

CodeCanyon setup-new Playbook the local MCP often validates

Deploy status Tell prod, preview, and local apart