qurl-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

CRITICAL RULES - NEVER VIOLATE

NEVER push directly to main branch. All changes MUST go through a Pull Request, no exceptions. This applies even for "quick fixes" or "urgent" changes. Create a branch, open a PR, and let CI run.

All commits must be GPG/SSH signed. Unsigned commits will be rejected by GitHub branch protection rules.

Code Change Workflow

Follow this process for all code changes:

1. Switch to main and fetch latest

   git checkout main && git pull origin main
   

2. Create branch for code change

   git checkout -b <type>/<short-description>
   

3. Make code changes - Think deeply about the implementation. Consider edge cases, error handling, and maintainability.

4. Run checks before committing

   npm run build && npm run lint && npm test
   

5. Create a PR

   git push -u origin <branch>
   gh pr create --title "<type>(scope): description" --body "..."
   

6. Wait for code review feedback - CI runs automatically. Review comments will be posted on the PR.

7. Address review feedback - Think critically about each suggestion.

8. Update the PR - Push fixes, update PR description if needed.

9. Repeat steps 6-8 until feedback requires no further action.

---

Project Overview

qURL MCP Server is a TypeScript Model Context Protocol server that exposes qURL operations as tools for AI agents. It supports local stdio and authenticated Streamable HTTP transports, and communicates with the qURL API plus an optional upload connector.

Architecture

qurl-mcp/
├── src/
│   ├── index.ts           # Entry point, env validation, stdio transport (API key or local CLI)
│   ├── qurl-cli.ts        # Bounded runner for the local qURL CLI (no-account stdio mode)
│   ├── http.ts            # Authenticated HTTP transport and runtime wiring
│   ├── http-sessions.ts   # Session registry, expiry, disconnect grace, and teardown
│   ├── http-public-routes.ts # Public legal/video routes, rate limits, and streaming
│   ├── http-config.ts     # Bounded listener/session/proxy configuration
│   ├── config.ts          # Shared qURL, connector, SMTP, and media config
│   ├── server.ts          # MCP server factory, tool/resource/prompt registration
│   ├── client.ts          # Adapter over the @layervai/qurl SDK (IQURLClient + QURLAPIError)
│   ├── tools/
│   │   ├── _shared.ts       # resourceIdSchema, zodErrorToToolResult
│   │   ├── duration.ts      # Duration grammar and bounds mirrored from qurl-service
│   │   ├── upload-mint-options.ts # Shared upload link options and descriptions
│   │   ├── create-qurl.ts
│   │   ├── consumer-access.ts # Private publishing, invitations, and consumer grants
│   │   ├── local-cli.ts     # No-account tools that run the local qURL CLI
│   │   ├── resolve-qurl.ts
│   │   ├── list-qurls.ts
│   │   ├── get-qurl.ts
│   │   ├── delete-qurl.ts
│   │   ├── extend-qurl.ts
│   │   ├── update-qurl.ts
│   │   ├── share-by-crid.ts
│   │   ├── mint-link.ts
│   │   ├── batch-create.ts
│   │   ├── revoke-qurl-token.ts
│   │   ├── update-qurl-token.ts
│   │   ├── list-qurl-sessions.ts
│   │   ├── terminate-qurl-sessions.ts
│   │   └── upload-*.ts    # File/data/text upload workflows
│   ├── auth/
│   │   ├── request-context.ts # Request-scoped credentials and validation state
│   │   └── static-bearer.ts   # Passthrough bearer verifier/client construction
│   ├── services/
│   │   ├── email.ts       # Policy-controlled SMTP delivery and quotas
│   │   ├── text-pdf.ts    # Bounded text-to-PDF generation
│   │   ├── html.ts        # Shared HTML escaping
│   │   ├── legal-pages.ts # Static legal document rendering
│   │   └── video-page.ts  # Optional public video page rendering
│   ├── resources/
│   │   ├── links.ts
│   │   └── usage.ts
│   └── prompts/
│       ├── secure-a-service.ts
│       ├── audit-links.ts
│       └── rotate-access.ts
├── dist/                  # Compiled output (gitignored)
├── package.json
└── tsconfig.json