feat(docs-mcp): @vertz/docs-mcp public MCP server for Vertz docs — GEO/SEO Phase 1.1

[matheuspoleza]

Description

Ship @vertz/docs-mcp as a public npm package so developers on Claude Code, Cursor, Windsurf, or Zed can install with one command and have Vertz docs available to their LLM in real time. Single highest-leverage action in the GEO/SEO strategy — bypasses the LLM training cycle.

Context

Part of GEO/SEO strategy v1 (28-day scope).

• Design doc: plans/geo-seo-strategy.md
• Full task spec: plans/geo-seo-strategy/phase-01-foundation-infra.md → Task 1
• Decision confirmed: indexes packages/mint-docs/ (not packages/site/pages/)
• Scope: docs + API reference only in v1. No live playground.

Acceptance Criteria

BDD scenarios

describe('Feature: @vertz/docs-mcp public MCP server', () => {
  describe('Given Claude Code is installed', () => {
    describe('When `claude mcp add vertz-docs -- npx -y @vertz/docs-mcp` runs', () => {
      it('then the MCP server connects successfully', () => {});
      it('then `search_docs("how to define an entity")` returns top 5 ranked doc excerpts', () => {});
      it('then `get_doc("guides/entities")` returns full guide markdown', () => {});
      it('then `list_guides()` returns the flat list of all guide paths', () => {});
    });
  });

  describe('Given the package is installed from npm', () => {
    describe('When `npx -y @vertz/docs-mcp` runs', () => {
      it('then a stdio MCP server starts within 2s', () => {});
      it('then the docs index is loaded from bundled JSON (no network)', () => {});
    });
  });
});

Checklist

• @vertz/docs-mcp published to npm with provenance
• MCP tools: search_docs, get_doc, list_guides, get_example
• Docs index built at prepublish from packages/mint-docs/
• README with install instructions for 4 clients: Claude Code, Cursor, Windsurf, Zed
• Integration test spawns server via MCP SDK + calls each tool
• Landing section "Use Vertz in your IDE" on vertz.dev/ home

Dependencies

• Blocked by: none (independent in v1)

Progress

• 2026-04-22: Opened