@neopress/mcp 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# @neopress/mcp
+
+Neopress MCP server for first-party AI agents.
+
+## Local Stdio
+
+Use this for Codex, Claude Code, and other local agents that can start a stdio
+MCP process.
+
+```bash
+neopress-mcp
+```
+
+Auth/session sources match the CLI:
+
+- `NEOPRESS_ACCESS_TOKEN`
+- `~/.config/neopress/tokens.json` from `neopress login`
+- `NEOPRESS_SITE_ID` or `neopress sites use <id>`
+- `NEOPRESS_BASE_URL` for staging/local API targets
+
+Stdio MCP can use `neopress_asset_upload_file` because it runs on the same
+machine as the agent and can read local file paths.
+
+The tool surface includes site/layout/page/collection/entry/form/asset/publish
+operations plus read-only analytics tools for traffic, forms, AI crawler reach,
+and Search Console.
+
+## Remote HTTP
+
+Use this for hosted MCP clients that connect over Streamable HTTP.
+
+```bash
+NEOPRESS_MCP_PUBLIC_URL=https://mcp.neopress.ai \
+NEOPRESS_BASE_URL=https://app.neopress.ai \
+neopress-mcp-http
+```
+
+Endpoints:
+
+| Method | Path                                      | Purpose                         |
+| ------ | ----------------------------------------- | ------------------------------- |
+| `POST` | `/mcp`                                    | MCP Streamable HTTP endpoint    |
+| `GET`  | `/.well-known/oauth-protected-resource/mcp` | OAuth protected resource metadata |
+| `GET`  | `/.well-known/oauth-authorization-server` | OAuth authorization server metadata |
+| `POST` | `/oauth/register`                         | Dynamic public client registration |
+| `GET`  | `/oauth/authorize`                        | Supabase OAuth PKCE redirect    |
+| `POST` | `/oauth/token`                            | Supabase PKCE/refresh proxy     |
+| `GET`  | `/healthz`                                | Liveness probe                  |
+| `GET`  | `/readyz`                                 | Readiness probe                 |
+
+Remote MCP requires OAuth bearer tokens for `/mcp`. It exposes dynamic client
+registration and PKCE token exchange for clients that support remote MCP OAuth.
+The access token is then used against the Neopress first-party `/api/v1` API,
+so tenant membership remains enforced by the app API.
+
+Remote MCP disables `neopress_asset_upload_file` because a hosted server cannot
+read the client's local filesystem. Use `neopress_asset_register` for public
+URLs, or use local stdio MCP for local file uploads.
+
+## Environment
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `PORT` | `4002` | Remote HTTP listen port |
+| `HOST` | `0.0.0.0` | Remote HTTP listen host |
+| `NEOPRESS_BASE_URL` | `https://app.neopress.ai` | Neopress API base URL |
+| `NEOPRESS_MCP_PUBLIC_URL` | request-derived | Public issuer/resource origin |
+| `NEOPRESS_MCP_CORS_ORIGINS` | local dev origins | Comma-separated allowlist or `*` |
+| `NEOPRESS_MCP_OAUTH_PROVIDER` | `google` | Supabase OAuth provider |
+| `NEOPRESS_MCP_OAUTH_CLIENT_SECRET` | generated at boot in non-production | Stable HMAC secret for signed dynamic client IDs; required when `NODE_ENV=production` |
+| `NEOPRESS_SUPABASE_URL` | Neopress Supabase project | Supabase Auth base URL |
+| `NEOPRESS_SUPABASE_ANON_KEY` | Neopress anon key | Supabase Auth anon key |
+| `NEOPRESS_MCP_AUTH_MODE` | `oauth` | `none` is dev/test only and rejected in production |
+
+## Docker / Cloud Run
+
+Build from the repo root:
+
+```bash
+docker build -f packages/mcp/Dockerfile -t neopress-mcp-server .
+docker run --rm -p 8080:8080 \
+  -e NEOPRESS_MCP_PUBLIC_URL=http://localhost:8080 \
+  neopress-mcp-server
+```
+
+Deploy through Artifact Registry / Cloud Run:
+
+```bash
+export NEOPRESS_MCP_OAUTH_CLIENT_SECRET="$(openssl rand -base64 32)"
+export NEOPRESS_MCP_PUBLIC_URL="https://mcp.neopress.ai"
+pnpm deploy:mcp
+```
+
+The deploy script defaults to project `inblog-ver-2`, region `us-west1`,
+repository `neopress`, and service `neopress-mcp-server`.
+
+## Official Client Drafts
+
+Submission-ready drafts live under `integrations/`:
+
+- `integrations/codex/config.example.toml` for Codex CLI/IDE MCP config.
+- `integrations/claude-code/setup.md` for Claude Code stdio/HTTP setup.
+- `integrations/claude-desktop/manifest.json` for Claude Desktop MCPB.
+- `integrations/claude-remote/connector-draft.md` for Claude remote MCP.
+- `integrations/chatgpt/app-draft.md` for ChatGPT Developer Mode.
+
+Stage a Claude Desktop MCPB directory after building:
+
+```bash
+pnpm --filter @neopress/mcp build
+pnpm --filter @neopress/mcp mcpb:stage
+pnpm dlx @anthropic-ai/mcpb pack packages/mcp/dist/mcpb/neopress
+```
+
+Do not submit the remote connector drafts until the production MCP origin,
+legal/support URLs, review workspace, and real client OAuth scans are verified.