@motiblog/mcp 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# MotiBlog MCP server
+
+Agent-first control surface over the MotiBlog API ([`docs/product/agent-first-direction.md`](../../docs/product/agent-first-direction.md), Direction B). Any MCP-capable agent — Claude Code, Cursor, Codex — can run a whole blog: propose topics, generate, review fact-check reports, approve through the governed gate, publish to targets, or **export content to deploy into its own codebase**.
+
+## Quick start — hosted (what a customer uses)
+
+The transport is mounted inside the API process, so the deployed API *is* the
+MCP endpoint. No install, no repository checkout, no separate service:
+
+```bash
+# 1. Get a per-project API key (dashboard: Project → Blog API → copy/rotate)
+# 2. Point any MCP-capable agent at the hosted endpoint:
+claude mcp add --transport http motiblog https://api.motiblog.ai/mcp \
+  --header "x-api-key: <your-key>"
+```
+
+Verify by hand:
+
+```bash
+curl -s https://api.motiblog.ai/mcp \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'x-api-key: <your-key>' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+## Quick start — local stdio (development)
+
+Running from the repository, for work on the tool layer itself:
+
+```bash
+claude mcp add motiblog \
+  --env MOTIBLOG_API_KEY=<your-key> \
+  --env MOTIBLOG_PROJECT_ID=<optional-default-project> \
+  -- pnpm --filter @motiblog/mcp start
+```
+
+The package is not published to npm and does not need to be: the hosted
+endpoint covers every customer path, and stdio is for people who have the
+repository anyway.
+
+Or use the committed [`.mcp.json`](../../.mcp.json): set `MOTIBLOG_API_KEY` in your environment and start Claude Code in the repo root.
+
+| Env var | Required | Meaning |
+|---|---|---|
+| `MOTIBLOG_API_KEY` | yes | Per-project key (`Project.blogApiKey`). Rotatable from dashboard. |
+| `MOTIBLOG_API_URL` | no | API base URL. Default `http://localhost:3001`. |
+| `MOTIBLOG_PROJECT_ID` | no | Default project; tools still accept explicit `project_id`. |
+
+## Remote agents: streamable HTTP
+
+### How it is served in production
+
+The handler (`src/http-handler.ts`) is mounted **inside the API process** as
+Express middleware — `apps/api/src/mcp/mcp.middleware.ts`, registered from
+`apps/api/src/main.ts`. Consequences worth knowing:
+
+- `POST api.motiblog.ai/mcp` works with the ordinary API deploy. There is no
+  second container and no extra reverse-proxy rule — which is exactly why the
+  endpoint was unreachable before: the code existed, the route did not.
+- It is registered with `app.use()` *before* `app.listen()`, so it sits ahead
+  of Nest's router. The global `ValidationPipe` and `TransformInterceptor`
+  never see it; if they did, they would rewrap the JSON-RPC envelope in the
+  API's `{ success, data }` shape and no client could parse it.
+- Nest's body-parser has already drained the request stream by then, so the
+  parsed body is handed to the transport explicitly. Skip that and the
+  transport waits on a stream that will never emit again.
+- Tool calls loop back to the same API over loopback, so an agent's key passes
+  the same guards an external caller meets. Being mounted in-process buys no
+  privileged shortcut. Override the loopback base with `MOTIBLOG_MCP_API_URL`.
+
+Covered by `apps/api/src/mcp/mcp.middleware.spec.ts`, which boots a real Nest
+app with those globals installed and asserts a full handshake survives.
+
+### Standalone server
+
+For local work, or to serve MCP from somewhere other than the API:
+
+```bash
+pnpm --filter @motiblog/mcp start:http
+# → http://127.0.0.1:3021/mcp  (POST, JSON-RPC; stateless)
+```
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `MOTIBLOG_HTTP_PORT` | `3021` | Listen port |
+| `MOTIBLOG_HTTP_HOST` | `127.0.0.1` | Bind host (use `0.0.0.0` behind a proxy) |
+
+Every request must carry the key (`x-api-key` or `Authorization: Bearer`); requests are authenticated and served independently (stateless — no session affinity).
+
+OAuth lands later — per-project keys are the MVP contract per `docs/product/agent-first-direction.md`.
+
+## Publishing to npm
+
+The package is publish-ready but **not yet published**. Until it is, leave the
+"no published npm package" line on `/mcp` and in `llms.txt` alone — an agent
+that reads an install instruction and hits a 404 is worse off than one told
+the truth.
+
+Prerequisites, all of which are a human's job:
+
+1. An npm account, and membership of an org named `motiblog` (the `@motiblog`
+   scope). A free org is enough — scoped packages publish publicly with
+   `access: public`, already set in `publishConfig`.
+2. `npm login` on the machine doing the publish.
+
+Then, from `apps/mcp`:
+
+```bash
+pnpm publish --access public          # runs tsup via prepublishOnly
+```
+
+Verify before you push the button:
+
+```bash
+pnpm pack                              # writes motiblog-mcp-<version>.tgz
+tar -tzf motiblog-mcp-*.tgz            # dist/ + README.md, nothing else
+tar -xzOf motiblog-mcp-*.tgz package/package.json | grep -E '"main"|"bin"'
+```
+
+Two things that must stay true, and both are easy to break:
+
+- **`@motiblog/shared` is bundled, not depended on.** It is a workspace
+  package that will never exist on npm, so `tsup.config.ts` lists it under
+  `noExternal` and the manifest keeps it in `devDependencies`. Move it back to
+  `dependencies` and every install resolves fine right up until the first
+  `export_blog` call. `grep -c '@motiblog/shared' dist/*.js` must print 0.
+- **`main` differs between the workspace and the tarball.** The repo consumes
+  raw TypeScript (`src/lib.ts`) because `apps/api` imports this package in
+  process; npm consumers get `dist/lib.js`. `publishConfig` performs that swap
+  at publish time, so neither side needs the other's layout.
+
+Smoke-test the tarball the way a customer meets it:
+
+```bash
+mkdir /tmp/t && cd /tmp/t && npm init -y
+npm install /path/to/motiblog-mcp-<version>.tgz
+node -e "console.log(Object.keys(require('@motiblog/mcp')))"
+MOTIBLOG_HTTP_PORT=3098 node_modules/.bin/motiblog-mcp-http
+```
+
+## Entry points
+
+| File | Shape | Use |
+|---|---|---|
+| `src/lib.ts` | pure exports, no side effects | what `main` points at; what the API imports |
+| `src/index.ts` | executes on import | stdio server (`pnpm start`) |
+| `src/http.ts` | executes on import | standalone HTTP server (`pnpm start:http`) |
+
+Import the library surface, never an entry point — importing `index.ts` or
+`http.ts` starts a server as a side effect of the import.
+
+## The agent loop
+
+```
+list_projects → suggest_topics → approve_content_plan → generate_article
+      → list_review_queue → get_article (factCheckReport, seoScore)
+      → update_article (fix flagged claims / supply_product_fact)
+      → approve_publication → publish_to_integration …or… export_blog
+```
+
+`get_pipeline_logs` diagnoses failures; `list_refresh_suggestions` finds decaying published posts worth refreshing; `start_pipeline` runs the fully autonomous crawl→plan→generate loop when you want hands-off operation.
+
+## Tools
+
+### Discovery & system
+| Tool | Notes |
+|---|---|
+| `list_projects` | All accessible projects + approval/quota settings |
+| `get_project` | Full pipeline config, positioning inputs |
+| `start_pipeline` | Autonomous crawl→plan→generate run |
+| `get_pipeline_status` | Run state + steps |
+
+### Topics & planning
+| Tool | Notes |
+|---|---|
+| `suggest_topics` | Add topic(s) to content plan (DRAFT entries) |
+| `list_content_plans` | Plan queue with statuses |
+| `approve_content_plan` | Clear a plan entry for generation |
+| `regenerate_content_plan` | AI-rewrite of a plan entry |
+| `generate_article` | Full pipeline from APPROVED plan |
+| `get_calendar` | Scheduled entries between two ISO dates |
+
+### Review loop (the governance core)
+| Tool | Notes |
+|---|---|
+| `list_review_queue` | Articles by lifecycle status (default REVIEW) |
+| `get_article` | Full markdown + `factCheckReport`, `topicGate`, seoScore, optional per-phase logs |
+| `update_article` | Edit content/title/meta/status — how agents answer fact-check flags |
+| `approve_publication` | Governed approval gate; `publish_now=true` publishes immediately |
+| `schedule_publication` | Set/clear scheduled publish time |
+
+### Regeneration ops
+| Tool | Notes |
+|---|---|
+| `regenerate_article` | Full rerun (destructive) |
+| `regenerate_chapter` | One section only (safe) |
+| `get_pipeline_logs` | Phase telemetry: status, tokens, USD cost |
+| `list_refresh_suggestions` | GSC-driven decay candidates across projects |
+
+### Publishing targets
+| Tool | Notes |
+|---|---|
+| `list_integrations` | WEBHOOK/WORDPRESS/GHOST/WEBFLOW/SHOPIFY/DEVTO/SANITY/CUSTOM_API |
+| `create_webhook_integration` | Push target for your own infra; deliveries signed `X-Signature: sha256=HMAC(secret)` |
+| `test_integration` | `ping` or `full` connection test |
+| `publish_to_integration` | APPROVED article → PUBLISHING → PUBLISHED |
+| `retry_publish` | Retry failed attempt |
+| `list_publish_logs` | Success/failure history with provider errors |
+
+### Agent-supplied knowledge
+| Tool | Notes |
+|---|---|
+| `add_keyword` / `list_keywords` | SEO keywords driving topic relevance |
+| `supply_product_fact` / `list_product_facts` | Ground truth enforced by strict fact-checking — supply BEFORE generation |
+
+### Export (deploy it yourself)
+| Tool | Notes |
+|---|---|
+| `export_blog` | Writes `{out_dir}/{slug}/index.md` (+ YAML frontmatter incl. `motiblogArticleId`) and `manifest.json`. Portable GFM: single H1, `<img>`→markdown images, iframes→watch links. Drop into Astro/Next/Jekyll/Hugo/plain git and deploy anywhere. |
+
+## Security model
+
+- The API key authenticates as the **project owner** on every existing route — ownership checks are unchanged; there is no privilege escalation.
+- **Admin routes refuse API keys** (`AdminGuard` rejects machine callers), even if the owner is an admin.
+- Publication always passes the typed approval gate with provenance — MCP adds no bypass.
+- Keys are per-project and rotatable; rotate immediately if exposed.
+- Rate limiting: global ThrottlerGuard applies unchanged.
+
+## Development
+
+```bash
+pnpm --filter @motiblog/mcp test   # jest unit tests (client envelope handling, export format)
+pnpm --filter @motiblog/mcp lint   # tsc --noEmit
+pnpm --filter @motiblog/mcp dev    # tsx watch (restart your MCP client after edits)
+```

package/dist/http.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { createServer } from 'http';
+
+/**
+ * MotiBlog MCP server — standalone streamable HTTP entrypoint.
+ *
+ * This is the local/self-hosted way to serve remote agents. In production the
+ * same handler is mounted inside the API process instead, so the endpoint is
+ * `POST api.motiblog.ai/mcp` with no extra service and no extra proxy rule —
+ * see apps/api/src/mcp/mcp.middleware.ts.
+ *
+ * Stateless: every request authenticates with its own per-project API key and
+ * gets a fresh server + transport (no session affinity needed).
+ *
+ * Env:
+ *   MOTIBLOG_API_URL    — API base for tool calls (default http://localhost:3001)
+ *   MOTIBLOG_HTTP_PORT  — listen port (default 3021)
+ *   MOTIBLOG_HTTP_HOST  — bind host (default 127.0.0.1; use 0.0.0.0 behind a proxy)
+ *   MOTIBLOG_PROJECT_ID — optional default project
+ *
+ * Auth: `x-api-key: <key>` or `Authorization: Bearer <key>` on every request.
+ */
+interface HttpServerOptions {
+    port: number;
+    host: string;
+    apiBaseUrl: string;
+    defaultProjectId?: string;
+}
+declare function startHttpServer(opts: HttpServerOptions): ReturnType<typeof createServer>;
+
+export { type HttpServerOptions, startHttpServer };