n2n-post2site 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to N2N Post2Site are documented in this file.
 
+## Unreleased
+
+## [0.1.4] - 2026-06-24
+
+### Changed
+
+- **Breaking:** renamed the `n2n_get_product_context` tool to `n2n_get_scope_context`, and the backend endpoint from `GET /products/{content_scope}` to `GET /scopes/{content_scope}`.
+- Treat `content_scope` as generic `kind:key` metadata. Client-side validation now only checks the `kind:key` format; whether a scope is required or prohibited for a content type is decided by the backend (`capabilities.content.content_scope.required_for_types`).
+- Relaxed `type` and `locale` tool inputs from fixed enums to free strings; the backend's `capabilities` is the source of truth for supported values. `status` remains an enum.
+- Genericized tool descriptions and documentation to remove product-only assumptions.
+
+### Removed
+
+- Removed the client-side `type`/`content_scope` coupling (`assertContentPostShape`), replaced by a format-only `assertContentScopeFormat`.
+- Removed the internal `docs/REFACTOR_PLAN.md` working document.
+
+## [0.1.3] - 2026-06-17
+
+### Added
+
+- Added `n2n_list_drafts` for listing unpublished drafts through the existing posts endpoint with `status=draft`.
+- Added `n2n_update_draft`, which reads the target post first and refuses to patch unless the backend reports `status: "draft"`.
+- Added `docs/ARCHITECTURE.md` to document runtime layers, module boundaries, and request flow.
+
+### Changed
+
+- Added `docs/ARCHITECTURE.md` to the README related docs list.
+- Bumped package version to `0.1.3`.
+
 ## [0.1.2] - 2026-06-15
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Datafrog LLC
+Copyright (c) 2026 N2NS Lab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,103 +1,101 @@
-# N2N Post2Site
+<p align="center">
+  <img src="./assets/n2n-post2site-logo.png" width="128" alt="n2n-post2site logo">
+</p>
 
-AI-assisted content publishing MCP server for blogs and product guides.
+# n2n-post2site
+
+AI-assisted content publishing MCP server for blogs, guides, and other categorized content.
 
 [![npm version](https://img.shields.io/npm/v/n2n-post2site)](https://www.npmjs.com/package/n2n-post2site)
 [![npm total downloads](https://img.shields.io/npm/dt/n2n-post2site)](https://www.npmjs.com/package/n2n-post2site)
-[![license](https://img.shields.io/github/license/n2ns/n2n-post2site)](https://github.com/n2ns/n2n-post2site/blob/main/LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
 [![node version](https://img.shields.io/node/v/n2n-post2site)](https://nodejs.org)
-[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)
 
-N2N Post2Site lets an AI assistant draft, edit, review, and publish website content through a narrow Content Publishing API Contract. It is built for teams that want AI-assisted blog posts, technical notes, changelogs, and product guides without giving the assistant database access, shell access, deployment access, payment access, or user administration access.
+---
+
+> **Draft with AI. Publish with intent.**
+
+n2n-post2site is an open-source Model Context Protocol (MCP) server that lets an AI assistant draft, edit, review, and publish website content through a narrow Content Publishing API Contract. It is a local MCP bridge between your IDE assistant and your website content API — intentionally small, with no database access, shell access, deployment access, payment access, or user administration access.
 
-It is intentionally small: a local MCP bridge between your IDE assistant and your website content API. Your website remains responsible for authentication, validation, storage, preview, publishing rules, and audit behavior.
+## 📚 Contents
 
-## Quick summary
+- [What is n2n-post2site?](#-what-is-n2n-post2site)
+- [Architecture](#️-architecture)
+- [Publishing model](#-publishing-model)
+- [Quick start](#-quick-start)
+- [Backend API contract](#-backend-api-contract)
+- [MCP tools](#️-mcp-tools)
+- [Content format](#-content-format)
+- [Security and governance notes](#-security-and-governance-notes)
+- [Related docs](#-related-docs)
 
-- Runs locally as an MCP server.
-- Connects to one website content API through `CONTENT_API_BASE_URL` and `CONTENT_API_KEY`.
-- Creates drafts by default.
-- Publishes only through an explicit publish tool.
-- Submits one locale per create or update call.
-- Uses Markdown-first content, with optional inline HTML when your site supports it.
-- Reads product context before drafting product guides.
-- Does not expose database, shell, server, payment, user, pricing, or delete operations.
+## 💡 What is n2n-post2site?
 
-## When to use it
+n2n-post2site gives AI coding assistants a structured path to draft and publish website content without exposing the database, file system, or deployment layer. Your backend implements the Content Publishing API Contract; the MCP server forwards AI tool calls to it.
 
-Use N2N Post2Site when you want an AI assistant to help with:
+Use it for blog posts, product guides, technical notes, release notes, and localized article drafts. It is not a CMS — no admin panel, no storage backend, no image uploads (v1), no deployment workflow.
+
+## 🏗️ Architecture
+
+```text
+┌─────────────────────────────┐
+│     AI coding assistant     │
+│   (Claude, Cursor, VS Code) │
+└──────────────┬──────────────┘
+               │ MCP tool calls (stdio)
+               ▼
+┌─────────────────────────────┐
+│        n2n-post2site        │
+│     MCP server · 9 tools    │
+│  validate → map → HTTP call │
+└──────────────┬──────────────┘
+               │ HTTPS + site-scoped API key
+               ▼
+┌─────────────────────────────┐
+│   Your backend content API  │
+│  (Content Publishing API    │
+│   Contract)                 │
+│  owns storage, auth, policy │
+└─────────────────────────────┘
+```
 
-- Company blog posts.
-- Product guides.
-- Technical field notes.
-- Release notes and changelogs.
-- Localized article drafts.
-- Safe updates to existing website content.
+- **The MCP server is a thin bridge**: it validates tool input, maps it to the contract, and forwards HTTP calls. It owns no persistence, authorization, or review policy.
+- **The backend owns the truth**: storage, publishing state, and access control all live behind the contract.
+- **One server, one site**: each MCP instance is bound to a single website through `CONTENT_API_BASE_URL` and `CONTENT_API_KEY`.
 
-Do not use it as a CMS. It does not provide an admin panel, database schema, storage backend, preview system, deployment workflow, or image upload service.
+See [Architecture](./docs/ARCHITECTURE.md) for the full layer breakdown.
 
-## Publishing model
+## 📰 Publishing model
 
-N2N Post2Site works with two publishing spaces:
+n2n-post2site classifies content with an optional `content_scope`:
 
-| Space | `content_scope` | Example |
+| Content | `content_scope` | Example |
 |---|---|---|
-| Company blog | omitted or empty | technical notes, announcements, changelogs |
-| Product guide | `kind:key` | `product:evisa-helper` |
+| Unscoped | omitted or empty | technical notes, announcements, changelogs |
+| Scoped | `kind:key` | `product:example-product` |
 
-The backend defines which scopes are valid. A product guide should only be written after the assistant reads controlled product context with `n2n_get_product_context`.
+The backend defines which `content_scope` kinds are valid and which content types require one. Scoped content should only be written after the assistant reads controlled context with `n2n_get_scope_context`.
 
 The assistant should follow this workflow:
 
 1. Call `n2n_get_capabilities`.
 2. Search existing content with `n2n_list_posts`.
-3. For product guides, call `n2n_get_product_context`.
+3. For scoped content, call `n2n_get_scope_context`.
 4. Create or update one locale at a time.
-5. Review the draft.
-6. Publish only through `n2n_publish_post`.
+5. Resume unfinished work with `n2n_list_drafts`, `n2n_get_post`, and `n2n_update_draft`.
+6. Review the draft.
+7. Publish only through `n2n_publish_post`.
 
-## Requirements
+## 🚀 Quick start
 
-- Node.js 22+
-- An MCP-capable client or IDE
-- A site-scoped content API token
-- A backend that implements the Content Publishing API Contract
+**Requirements**: Node.js 22+, an MCP-capable client, a site-scoped API key, and a backend that implements the [Content Publishing API Contract](./docs/BACKEND_API.md).
 
-## Install
-
-For local development:
-
-```bash
-npm install
-npm run build
-npm run check
-```
-
-For MCP clients, use the published package after it is available on npm:
-
-```bash
-npx -y n2n-post2site
-```
+> **Just trying it out?** Run the [mock backend](./examples/mock-backend/) for a zero-dependency local server that implements the full contract — no website required.
 
-## Configuration
+### 1. Configure your MCP client
 
-Set these environment variables in your MCP client configuration:
-
-```env
-CONTENT_API_BASE_URL=https://example.com/api/v1/mcp
-CONTENT_API_KEY=change-me
-```
-
-`CONTENT_API_BASE_URL` is the base URL of your protected content API. The backend should expose `/capabilities`, `/products/{content_scope}`, and `/posts` relative to this base URL.
-
-Keep path mapping and field mapping in the backend adapter, not in MCP client configuration. The MCP config should only need a base URL and an API key.
-
-Do not put API keys in prompts, article content, README examples, or screenshots.
-
-## MCP client examples
-
-### Using the npm package
+Using the npm package:
 
 ```json
 {
@@ -106,15 +104,15 @@ Do not put API keys in prompts, article content, README examples, or screenshots
       "command": "npx",
       "args": ["-y", "n2n-post2site"],
       "env": {
-        "CONTENT_API_BASE_URL": "https://example.com/api/v1/mcp",
-        "CONTENT_API_KEY": "change-me"
+        "CONTENT_API_BASE_URL": "https://your-site.com/api/v1/mcp",
+        "CONTENT_API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-### Using a local checkout
+Using a local checkout:
 
 ```json
 {
@@ -123,185 +121,34 @@ Do not put API keys in prompts, article content, README examples, or screenshots
       "command": "node",
       "args": ["/path/to/n2n-post2site/dist/index.js"],
       "env": {
-        "CONTENT_API_BASE_URL": "https://example.com/api/v1/mcp",
-        "CONTENT_API_KEY": "change-me"
+        "CONTENT_API_BASE_URL": "https://your-site.com/api/v1/mcp",
+        "CONTENT_API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-Bind one MCP server configuration to exactly one website. Do not ask the AI assistant to choose a `site_id` in tool arguments.
-
-## Backend API contract
-
-The backend should support these endpoints relative to `CONTENT_API_BASE_URL`:
-
-```http
-GET    /capabilities
-GET    /products/{content_scope}
-GET    /posts
-POST   /posts
-GET    /posts/{id_or_slug}
-PATCH  /posts/{id_or_slug}
-POST   /posts/{id_or_slug}/publish
-```
+- `CONTENT_API_BASE_URL`: base URL of your protected content API. Keep path and field mapping in the backend adapter.
+- `CONTENT_API_KEY`: site-scoped API key. Do not put it in prompts, article content, or screenshots.
 
-### `GET /capabilities`
+Bind one server instance to exactly one website.
 
-Returns the publishing contract for AI clients, including:
+## 🔗 Backend API contract
 
-- Supported content types.
-- Supported statuses.
-- Supported locales.
-- Single-locale input fields.
-- `content_scope` rules.
-- Available product guide scopes.
-- Safety boundaries.
+n2n-post2site connects to any backend that implements the Content Publishing API Contract. The contract defines the required endpoints, payload rules, and security requirements.
 
-### `GET /products/{content_scope}`
+See **[Backend API Contract](./docs/BACKEND_API.md)** for the full specification.
 
-Returns controlled product context before drafting product guides.
+## 🛠️ MCP tools
 
-Expected fields:
+- **Discovery** (`n2n_get_capabilities`, `n2n_list_posts`, `n2n_get_scope_context`): read backend capabilities, list existing posts, and load scope context before drafting.
+- **Drafting** (`n2n_create_post`, `n2n_update_post`, `n2n_update_draft`, `n2n_list_drafts`, `n2n_get_post`): create posts, update posts one locale at a time, and resume unpublished drafts.
+- **Publishing** (`n2n_publish_post`): publish an approved draft through an explicit publish step.
 
-- `content_scope`: confirms the valid product guide scope.
-- `canonical_url`: product page for deeper reading, links, and citations.
-- `docs_url`: docs or guide index to prefer for tutorials.
-- `summary`: controlled product summary.
-- `key_points`: controlled facts the assistant may rely on.
-- `do_not_claim`: claims the assistant must not make.
-
-### Create and update payloads
-
-Create and update calls use one locale per request:
-
-```json
-{
-  "slug": "example-product-guide",
-  "type": "guide",
-  "content_scope": "product:example-product",
-  "locale": "en",
-  "title": "How to Use Example Product",
-  "excerpt": "A short guide to using the example product.",
-  "content": "## Overview\n\nMarkdown content..."
-}
-```
-
-Rules:
-
-- `title` is plain text.
-- `excerpt` is plain text.
-- `content` is Markdown.
-- Inline HTML is allowed when useful.
-- Full HTML documents with `<html>`, `<head>`, or `<body>` are not allowed.
-- Create/update must not accept `status`, `published_at`, `user_id`, or `author`.
-- Publishing state changes only through `/posts/{id_or_slug}/publish`.
-
-Backends may return `missing_locales` and `next_actions` after create, update, or publish. The assistant should add missing language versions with additional `n2n_update_post` calls instead of asking the backend to auto-translate.
-
-## MCP tools
-
-### `n2n_get_capabilities`
-
-Read backend capabilities before creating or updating content.
-
-```json
-{}
-```
-
-### `n2n_list_posts`
-
-Search existing posts before drafting new content.
-
-```json
-{
-  "status": "draft",
-  "type": "guide",
-  "content_scope": "product:example-product",
-  "q": "setup guide",
-  "per_page": 20
-}
-```
-
-`status` is only a filter here. Do not send `status` in create or update calls.
-
-### `n2n_get_post`
-
-Read an existing post before updating it, completing missing locales, or writing a follow-up.
-
-```json
-{
-  "id_or_slug": "example-product-guide"
-}
-```
-
-### `n2n_get_product_context`
-
-Read controlled product facts before drafting a product guide.
-
-```json
-{
-  "content_scope": "product:example-product"
-}
-```
-
-### `n2n_create_post`
-
-Create a draft. Publishing is separate.
-
-Company blog example:
-
-```json
-{
-  "slug": "content-workflow-notes",
-  "type": "technical",
-  "locale": "en",
-  "title": "Content Workflow Notes",
-  "excerpt": "Practical notes from shipping a content workflow.",
-  "content": "## Notes\n\nMarkdown content..."
-}
-```
-
-Product guide example:
-
-```json
-{
-  "slug": "example-product-guide",
-  "type": "guide",
-  "content_scope": "product:example-product",
-  "locale": "en",
-  "title": "How to Use Example Product",
-  "excerpt": "A short guide to using the example product.",
-  "content": "## Overview\n\nMarkdown content..."
-}
-```
-
-### `n2n_update_post`
-
-Update one locale of an existing post. Call `n2n_get_post` first.
-
-```json
-{
-  "id_or_slug": "example-product-guide",
-  "locale": "de",
-  "title": "So verwenden Sie Example Product",
-  "excerpt": "A localized summary for the selected locale.",
-  "content": "## Ueberblick\n\nLocalized Markdown content..."
-}
-```
-
-### `n2n_publish_post`
-
-Publish an existing draft.
-
-```json
-{
-  "id_or_slug": "example-product-guide"
-}
-```
+See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
-## Content format
+## 📝 Content format
 
 - Submit one locale per create or update call.
 - Use Markdown for `content`.
@@ -317,9 +164,9 @@ Image example:
 ![Product dashboard showing content status](/images/guides/content-status.png)
 ```
 
-## Safety boundaries
+## 🔐 Security and governance notes
 
-N2N Post2Site should not expose:
+n2n-post2site should not expose:
 
 - Delete operations.
 - Product configuration writes.
@@ -339,14 +186,20 @@ Recommended backend behavior:
 - Keep create/update and publish separate.
 - Set `published_at` on the backend, not from MCP input.
 
-## Laravel backend package direction
+## 📖 Related docs
 
-A Laravel package can implement the HTTP side of this contract for multiple Laravel sites without copying controllers between projects. N2N Post2Site should stay a generic MCP client of that contract.
+- **[Backend API Contract](./docs/BACKEND_API.md)**: Endpoints, payload rules, and security requirements for backend implementors.
+- **[Architecture](./docs/ARCHITECTURE.md)**: Runtime layers, module boundaries, and request flow in the MCP server.
+- **[Tools reference](./docs/TOOLS_REFERENCE.md)**: MCP tool parameter schemas and call examples.
+- **[Roadmap](./ROADMAP.md)**: Planned features and what's coming next.
+- **[Changelog](./CHANGELOG.md)**: Version history and release notes.
+- **[Contributing](./CONTRIBUTING.md)**: How to report issues and contribute.
+- **[Security](./SECURITY.md)**: How to report vulnerabilities.
 
-## About N2NS Lab
+## 📄 License
 
-Built by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for AI-native developer tools.
+This project is licensed under the [MIT License](./LICENSE).
 
-Learn more: https://n2ns.com
+---
 
-Source repository: git@github.com:n2ns/n2n-post2site.git
+Built by [N2NS Lab](https://n2ns.com), an open-source lab for practical AI developer tools.

package/dist/content-client.js

@@ -1,10 +1,13 @@
+import { FetchHttpTransport } from './transport/http.js';
 const POSTS_PATH = '/posts';
 const CAPABILITIES_PATH = '/capabilities';
-const PRODUCTS_PATH = '/products';
+const SCOPES_PATH = '/scopes';
 export class ContentClient {
     config;
-    constructor(config) {
+    transport;
+    constructor(config, transport = new FetchHttpTransport(config)) {
         this.config = config;
+        this.transport = transport;
     }
     async getCapabilities() {
         return this.request(CAPABILITIES_PATH, { method: 'GET' });
@@ -12,18 +15,22 @@ export class ContentClient {
     async listPosts(input) {
         const params = new URLSearchParams();
         for (const [key, value] of Object.entries(input)) {
-            if (value === undefined)
+            if (value === undefined) {
                 continue;
+            }
             params.set(key, String(value));
         }
         const suffix = params.toString() ? `?${params.toString()}` : '';
         return this.request(`${POSTS_PATH}${suffix}`, { method: 'GET' });
     }
+    async listDrafts(input) {
+        return this.listPosts({ ...input, status: 'draft' });
+    }
     async getPost(idOrSlug) {
         return this.request(`${POSTS_PATH}/${encodeURIComponent(idOrSlug)}`, { method: 'GET' });
     }
-    async getProductContext(input) {
-        return this.request(`${PRODUCTS_PATH}/${encodeURIComponent(input.content_scope)}`, { method: 'GET' });
+    async getScopeContext(input) {
+        return this.request(`${SCOPES_PATH}/${encodeURIComponent(input.content_scope)}`, { method: 'GET' });
     }
     async createPost(input) {
         return this.request(POSTS_PATH, {
@@ -38,13 +45,18 @@ export class ContentClient {
             body: JSON.stringify(payload),
         });
     }
+    async updateDraft(input) {
+        const existingPost = await this.getPost(input.id_or_slug);
+        assertDraftStatus(existingPost);
+        return this.updatePost(input);
+    }
     async publishPost(idOrSlug) {
         return this.request(`${POSTS_PATH}/${encodeURIComponent(idOrSlug)}/publish`, {
             method: 'POST',
         });
     }
     async request(path, init) {
-        const response = await fetch(`${this.config.apiBaseUrl}${path}`, {
+        const response = await this.transport.request(path, {
             ...init,
             headers: {
                 Accept: 'application/json',
@@ -54,24 +66,31 @@ export class ContentClient {
                 ...(init.headers ?? {}),
             },
         });
-        const text = await response.text();
-        const body = parseJsonOrText(text);
         if (!response.ok) {
-            throw new Error(`Content API request failed: ${response.status} ${response.statusText}: ${formatBody(body)}`);
+            throw new Error(`Content API request failed: ${response.status} ${response.statusText}: ${formatBody(response.body)}`);
         }
-        return body;
+        return response.body;
     }
 }
-function parseJsonOrText(text) {
-    if (!text)
-        return null;
-    try {
-        return JSON.parse(text);
+function formatBody(body) {
+    return typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+}
+function assertDraftStatus(body) {
+    const status = extractPostStatus(body);
+    if (status === 'draft') {
+        return;
     }
-    catch {
-        return text;
+    if (status) {
+        throw new Error(`n2n_update_draft requires a draft post. Current status: ${status}.`);
     }
+    throw new Error('n2n_update_draft could not verify draft status. The backend GET /posts/{id_or_slug} response must include a status field.');
 }
-function formatBody(body) {
-    return typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+function extractPostStatus(body) {
+    const record = asRecord(body);
+    const post = asRecord(record?.blog_post) ?? asRecord(record?.data) ?? record;
+    const status = post?.status;
+    return typeof status === 'string' ? status : undefined;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }

package/dist/index.js

@@ -1,62 +1,8 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig } from './config.js';
-import { ContentClient } from './content-client.js';
-import { assertContentPostShape, capabilitiesSchema, createPostSchema, getPostSchema, listPostsSchema, productContextSchema, publishPostSchema, updatePostSchema, } from './schemas/blog-post.js';
-const server = new McpServer({
-    name: 'n2n-post2site',
-    version: '0.1.2',
-});
-const client = new ContentClient(loadConfig());
-server.tool('n2n_get_capabilities', 'Read the backend Content Publishing API Contract before creating or updating content. Use this to discover supported content types, locales, content_scope rules, and product guide scopes.', capabilitiesSchema.shape, async (input) => {
-    capabilitiesSchema.parse(input);
-    const result = await client.getCapabilities();
-    return textResult(result);
-});
-server.tool('n2n_list_posts', 'Search and list existing website articles or product guides before drafting new content. Use this to avoid duplicate topics and conflicting guidance. For product guides, filter by content_scope. Use content_scope="" for unscoped company blog posts when the backend supports it.', listPostsSchema.shape, async (input) => {
-    const parsed = listPostsSchema.parse(input);
-    const result = await client.listPosts(parsed);
-    return textResult(result);
-});
-server.tool('n2n_get_post', 'Read one existing article or guide by numeric ID or slug. Use this before updating a post, completing missing locales, or writing a follow-up article that depends on previous content.', getPostSchema.shape, async (input) => {
-    const parsed = getPostSchema.parse(input);
-    const result = await client.getPost(parsed.id_or_slug);
-    return textResult(result);
-});
-server.tool('n2n_get_product_context', 'Read the controlled product fact sheet before writing a product guide. The backend returns content_scope, canonical_url, docs_url, summary, key_points, and do_not_claim so the article does not invent product facts.', productContextSchema.shape, async (input) => {
-    const parsed = productContextSchema.parse(input);
-    assertContentPostShape({ type: 'guide', content_scope: parsed.content_scope });
-    const result = await client.getProductContext(parsed);
-    return textResult(result);
-});
-server.tool('n2n_create_post', 'Create an article draft or product guide draft with one locale per call. Before creating new content, search existing posts with n2n_list_posts to avoid duplicates. Before creating a product guide, also call n2n_get_product_context for the target content_scope and follow its canonical_url, docs_url, summary, key_points, and do_not_claim. content must be a Markdown document string; inline HTML is allowed when useful. title and excerpt must be plain text. The backend returns missing_locales when more language versions should be added. Use n2n_publish_post to publish.', createPostSchema.shape, async (input) => {
-    const parsed = createPostSchema.parse(input);
-    assertContentPostShape(parsed);
-    const result = await client.createPost(parsed);
-    return textResult(result);
-});
-server.tool('n2n_update_post', 'Update one locale of an existing article or guide by ID or slug. Always call n2n_get_post first so edits preserve existing content and metadata. content must be a Markdown document string; inline HTML is allowed when useful. title and excerpt must be plain text. Use repeated calls with different locale values to add missing language versions.', updatePostSchema.shape, async (input) => {
-    const parsed = updatePostSchema.parse(input);
-    assertContentPostShape(parsed);
-    const result = await client.updatePost(parsed);
-    return textResult(result);
-});
-server.tool('n2n_publish_post', 'Publish an existing article or guide by ID or slug. Publishing is intentionally separate from create/update to avoid accidental publication.', publishPostSchema.shape, async (input) => {
-    const parsed = publishPostSchema.parse(input);
-    const result = await client.publishPost(parsed.id_or_slug);
-    return textResult(result);
-});
-function textResult(value) {
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(value, null, 2),
-            },
-        ],
-    };
-}
+import { createServer } from './server.js';
+const server = createServer(loadConfig());
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/result.js

@@ -0,0 +1,10 @@
+export function createTextResult(value) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}

package/dist/schemas/blog-post.js

@@ -1,26 +1,26 @@
 import { z } from 'zod';
-export const contentTypeSchema = z.enum(['technical', 'announcement', 'changelog', 'guide']);
 export const statusSchema = z.enum(['draft', 'published']);
-export const localeSchema = z.enum(['en', 'zh_CN', 'es', 'de']);
 export const capabilitiesSchema = z.object({});
+const CONTENT_SCOPE_FORMAT = /^[a-z][a-z0-9_-]*:[a-z0-9][a-z0-9_-]*$/;
 export const listPostsSchema = z.object({
     status: statusSchema.optional().describe('Filter by publication status.'),
-    type: contentTypeSchema.optional().describe('Filter by content type. Use guide for product or collection guide articles.'),
-    content_scope: z.string().optional().describe('Optional site-defined canonical publishing scope for guides, products, or collections. Use kind:key, for example product:example-product. Use an empty string to list unscoped company blog posts when the backend supports it.'),
-    q: z.string().optional().describe('Search query across title, content, and translations.'),
+    type: z.string().optional().describe('Filter by content type. Call n2n_get_capabilities for supported types.'),
+    content_scope: z.string().optional().describe('Filter by content_scope (kind:key). Use an empty string to list unscoped posts when the backend supports it.'),
+    q: z.string().optional().describe('Search query across title and content.'),
     per_page: z.number().int().min(1).max(100).optional().describe('Page size. Defaults to the server value.'),
 });
+export const listDraftsSchema = listPostsSchema.omit({ status: true });
 export const getPostSchema = z.object({
     id_or_slug: z.string().min(1).describe('Numeric ID or slug of the article.'),
 });
-export const productContextSchema = z.object({
-    content_scope: z.string().min(1).describe('Product guide scope in kind:key format, for example product:evisa-helper. Read this before writing a product guide.'),
+export const scopeContextSchema = z.object({
+    content_scope: z.string().min(1).describe('Content scope in kind:key format, for example product:example. Read this before writing scoped content. Call n2n_get_capabilities for supported kinds.'),
 });
 export const createPostSchema = z.object({
     slug: z.string().min(1).describe('Globally unique URL slug.'),
-    type: contentTypeSchema.default('technical').describe('Use guide for product or collection guide articles.'),
-    content_scope: z.string().optional().describe('Required when type is guide. Use kind:key, for example product:example-product, project:example-project, or collection:example-collection.'),
-    locale: localeSchema.default('en').describe('Locale for this single-language submission. Submit one locale per tool call.'),
+    type: z.string().optional().describe('Content type. Call n2n_get_capabilities for supported types. The backend applies its default when omitted.'),
+    content_scope: z.string().optional().describe('Optional kind:key categorization, for example product:example. The backend requires it for certain content types; call n2n_get_capabilities for supported kinds, examples, and which types require it.'),
+    locale: z.string().optional().describe('Single-locale code for this submission. Submit one locale per call. Call n2n_get_capabilities for supported locales. The backend applies its default when omitted.'),
     title: z.string().min(1).describe('Plain text title for the selected locale. Do not use Markdown here.'),
     excerpt: z.string().optional().describe('Plain text summary for the selected locale. No Markdown headings, tables, or images.'),
     content: z.string().min(1).describe('Markdown article body for the selected locale. Markdown image syntax is allowed. Inline HTML is allowed when useful.'),
@@ -29,17 +29,15 @@ export const createPostSchema = z.object({
 export const updatePostSchema = createPostSchema.partial().extend({
     id_or_slug: z.string().min(1).describe('Numeric ID or slug of the article to update.'),
 });
+export const updateDraftSchema = updatePostSchema;
 export const publishPostSchema = getPostSchema;
-export function assertContentPostShape(input) {
-    const type = input.type ?? 'technical';
-    const content_scope = input.content_scope;
-    if (type === 'guide' && !content_scope) {
-        throw new Error('content_scope is required when type is guide. Use a kind:key value such as product:example-product, project:example-project, or collection:example-collection.');
-    }
-    if (type !== 'guide' && content_scope) {
-        throw new Error('content_scope is only allowed when type is guide. Omit content_scope for unscoped company blog posts.');
-    }
-    if (content_scope && !/^[a-z][a-z0-9_-]*:[a-z0-9][a-z0-9_-]*$/.test(content_scope)) {
-        throw new Error('content_scope must use kind:key format, for example product:example-product.');
+/**
+ * Contract-level format check only. Whether a content_scope is required or
+ * prohibited for a given type is decided by the backend (capabilities
+ * .content.content_scope.required_for_types) and enforced server-side.
+ */
+export function assertContentScopeFormat(contentScope) {
+    if (contentScope && !CONTENT_SCOPE_FORMAT.test(contentScope)) {
+        throw new Error('content_scope must use kind:key format, for example product:example.');
     }
 }

package/dist/server.js

@@ -0,0 +1,28 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ContentClient } from './content-client.js';
+import { registerCreatePostTool } from './tools/create-post.js';
+import { registerGetCapabilitiesTool } from './tools/get-capabilities.js';
+import { registerGetPostTool } from './tools/get-post.js';
+import { registerGetScopeContextTool } from './tools/get-scope-context.js';
+import { registerListDraftsTool } from './tools/list-drafts.js';
+import { registerListPostsTool } from './tools/list-posts.js';
+import { registerPublishPostTool } from './tools/publish-post.js';
+import { registerUpdateDraftTool } from './tools/update-draft.js';
+import { registerUpdatePostTool } from './tools/update-post.js';
+export function createServer(config) {
+    const client = new ContentClient(config);
+    const server = new McpServer({
+        name: 'n2n-post2site',
+        version: '0.1.2',
+    });
+    registerGetCapabilitiesTool(server, client);
+    registerListPostsTool(server, client);
+    registerListDraftsTool(server, client);
+    registerGetPostTool(server, client);
+    registerGetScopeContextTool(server, client);
+    registerCreatePostTool(server, client);
+    registerUpdatePostTool(server, client);
+    registerUpdateDraftTool(server, client);
+    registerPublishPostTool(server, client);
+    return server;
+}

package/dist/tools/create-post.js

@@ -0,0 +1,10 @@
+import { createTextResult } from '../result.js';
+import { assertContentScopeFormat, createPostSchema } from '../schemas/blog-post.js';
+export function registerCreatePostTool(server, client) {
+    server.tool('n2n_create_post', 'Create a content draft with one locale per call. Before creating new content, search existing posts with n2n_list_posts to avoid duplicates. Call n2n_get_capabilities to learn supported types and which require a content_scope; for scoped content also call n2n_get_scope_context and follow the returned facts. content must be a Markdown document string; inline HTML is allowed when useful. title and excerpt must be plain text. The backend returns missing_locales when more language versions should be added. Use n2n_publish_post to publish.', createPostSchema.shape, async (input) => {
+        const parsed = createPostSchema.parse(input);
+        assertContentScopeFormat(parsed.content_scope);
+        const result = await client.createPost(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/tools/get-capabilities.js

@@ -0,0 +1,9 @@
+import { createTextResult } from '../result.js';
+import { capabilitiesSchema } from '../schemas/blog-post.js';
+export function registerGetCapabilitiesTool(server, client) {
+    server.tool('n2n_get_capabilities', 'Read the backend Content Publishing API Contract before creating or updating content. Use this to discover supported content types, locales, content_scope rules (kinds, examples, which types require a scope), and available scopes.', capabilitiesSchema.shape, async (input) => {
+        capabilitiesSchema.parse(input);
+        const result = await client.getCapabilities();
+        return createTextResult(result);
+    });
+}

package/dist/tools/get-post.js

@@ -0,0 +1,9 @@
+import { createTextResult } from '../result.js';
+import { getPostSchema } from '../schemas/blog-post.js';
+export function registerGetPostTool(server, client) {
+    server.tool('n2n_get_post', 'Read one existing article or guide by numeric ID or slug. Use this before updating a post, completing missing locales, or writing a follow-up article that depends on previous content.', getPostSchema.shape, async (input) => {
+        const parsed = getPostSchema.parse(input);
+        const result = await client.getPost(parsed.id_or_slug);
+        return createTextResult(result);
+    });
+}

package/dist/tools/get-scope-context.js

@@ -0,0 +1,10 @@
+import { createTextResult } from '../result.js';
+import { assertContentScopeFormat, scopeContextSchema } from '../schemas/blog-post.js';
+export function registerGetScopeContextTool(server, client) {
+    server.tool('n2n_get_scope_context', 'Read the controlled context for a content_scope before writing scoped content. The backend returns content_scope plus host-defined facts (for example canonical_url, docs_url, summary, key_points, do_not_claim) so the article does not invent facts.', scopeContextSchema.shape, async (input) => {
+        const parsed = scopeContextSchema.parse(input);
+        assertContentScopeFormat(parsed.content_scope);
+        const result = await client.getScopeContext(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/tools/list-drafts.js

@@ -0,0 +1,9 @@
+import { createTextResult } from '../result.js';
+import { listDraftsSchema } from '../schemas/blog-post.js';
+export function registerListDraftsTool(server, client) {
+    server.tool('n2n_list_drafts', 'List unpublished draft posts. Use this before resuming previous AI-written drafts. This tool always filters status=draft; use type, content_scope, q, and per_page to narrow the results.', listDraftsSchema.shape, async (input) => {
+        const parsed = listDraftsSchema.parse(input);
+        const result = await client.listDrafts(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/tools/list-posts.js

@@ -0,0 +1,9 @@
+import { createTextResult } from '../result.js';
+import { listPostsSchema } from '../schemas/blog-post.js';
+export function registerListPostsTool(server, client) {
+    server.tool('n2n_list_posts', 'Search and list existing posts before drafting new content, to avoid duplicate topics and conflicting guidance. Filter by content_scope for scoped content, or content_scope="" for unscoped posts when the backend supports it.', listPostsSchema.shape, async (input) => {
+        const parsed = listPostsSchema.parse(input);
+        const result = await client.listPosts(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/tools/publish-post.js

@@ -0,0 +1,9 @@
+import { createTextResult } from '../result.js';
+import { publishPostSchema } from '../schemas/blog-post.js';
+export function registerPublishPostTool(server, client) {
+    server.tool('n2n_publish_post', 'Publish an existing article or guide by ID or slug. Publishing is intentionally separate from create/update to avoid accidental publication.', publishPostSchema.shape, async (input) => {
+        const parsed = publishPostSchema.parse(input);
+        const result = await client.publishPost(parsed.id_or_slug);
+        return createTextResult(result);
+    });
+}

package/dist/tools/update-draft.js

@@ -0,0 +1,10 @@
+import { createTextResult } from '../result.js';
+import { assertContentScopeFormat, updateDraftSchema } from '../schemas/blog-post.js';
+export function registerUpdateDraftTool(server, client) {
+    server.tool('n2n_update_draft', 'Update one locale of an unpublished draft by ID or slug. The client reads the post first and refuses to patch unless the backend reports status=draft. Use n2n_list_drafts and n2n_get_post before calling this tool.', updateDraftSchema.shape, async (input) => {
+        const parsed = updateDraftSchema.parse(input);
+        assertContentScopeFormat(parsed.content_scope);
+        const result = await client.updateDraft(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/tools/update-post.js

@@ -0,0 +1,10 @@
+import { createTextResult } from '../result.js';
+import { assertContentScopeFormat, updatePostSchema } from '../schemas/blog-post.js';
+export function registerUpdatePostTool(server, client) {
+    server.tool('n2n_update_post', 'Update one locale of an existing article or guide by ID or slug. Always call n2n_get_post first so edits preserve existing content and metadata. content must be a Markdown document string; inline HTML is allowed when useful. title and excerpt must be plain text. Use repeated calls with different locale values to add missing language versions.', updatePostSchema.shape, async (input) => {
+        const parsed = updatePostSchema.parse(input);
+        assertContentScopeFormat(parsed.content_scope);
+        const result = await client.updatePost(parsed);
+        return createTextResult(result);
+    });
+}

package/dist/transport/http.js

@@ -0,0 +1,28 @@
+export class FetchHttpTransport {
+    baseUrl;
+    constructor(config) {
+        this.baseUrl = config.apiBaseUrl;
+    }
+    async request(path, init) {
+        const response = await fetch(`${this.baseUrl}${path}`, init);
+        const text = await response.text();
+        const body = parseJsonOrText(text);
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            ok: response.ok,
+            body,
+        };
+    }
+}
+function parseJsonOrText(text) {
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# N2N Post2Site Architecture
+
+This document describes the current architecture of `n2n-post2site`. The goal is to keep boundaries clear, preserve interface compatibility, and give future changes stable extension points.
+
+## 1. What it is
+
+`n2n-post2site` is an MCP server. It:
+
+- Loads environment configuration and creates an MCP server instance.
+- Exposes nine content publishing tools to MCP clients.
+- Translates tool arguments into HTTP calls against a backend content API.
+- Wraps backend responses into MCP-displayable text.
+
+It does not own persistence, authorization, review policy, or content-ranking decisions. Those belong to the backend API provider.
+
+## 2. Layers
+
+### 2.1 Entry (`src/index.ts`)
+
+- Creates the server via `createServer(loadConfig())`.
+- Connects to the MCP client over `StdioServerTransport`.
+- Owns only process lifecycle and failure output.
+
+### 2.2 Configuration (`src/config.ts`)
+
+- Reads `CONTENT_API_BASE_URL` and `CONTENT_API_KEY`.
+- Fails fast on missing values.
+- Normalizes trailing slashes on `CONTENT_API_BASE_URL`.
+
+### 2.3 Assembly (`src/server.ts`)
+
+Build-and-register only:
+
+1. Construct `ContentClient`.
+2. Create `McpServer`.
+3. Register the nine tools, in order:
+
+- `n2n_get_capabilities`
+- `n2n_list_posts`
+- `n2n_list_drafts`
+- `n2n_get_post`
+- `n2n_get_scope_context`
+- `n2n_create_post`
+- `n2n_update_post`
+- `n2n_update_draft`
+- `n2n_publish_post`
+
+### 2.4 Tools (`src/tools/*.ts`)
+
+Each file is one MCP tool:
+
+- Validate input (Zod schema + lightweight assertions).
+- Call the matching `ContentClient` method.
+- Return a uniform `text` result.
+
+Tools do not deal with low-level HTTP, headers, JSON parsing, or path building.
+
+### 2.5 Transport and client
+
+- `src/transport/http.ts` — the `HttpTransport` interface and the default `FetchHttpTransport` wrapping `fetch`; handles response parsing (JSON/text) and status passthrough.
+- `src/content-client.ts` — builds paths and HTTP methods, injects auth headers (`X-API-KEY` / `Authorization`), turns non-2xx responses into errors, assembles list and route parameters, and implements the `updateDraft` flow:
+  1. `GET /posts/{id_or_slug}`
+  2. require `status === 'draft'`
+  3. then `PATCH /posts/{id_or_slug}`
+
+### 2.6 Schemas and validation (`src/schemas/blog-post.ts`)
+
+- Zod schemas define every tool's input.
+- `type` and `locale` are free strings; the backend is the source of truth for supported values (discoverable via `n2n_get_capabilities`).
+- `assertContentScopeFormat` performs a contract-level format check only: when present, `content_scope` must be `kind:key`. Whether a scope is *required* or *prohibited* for a given type is decided and enforced by the backend (`capabilities.content.content_scope.required_for_types`).
+
+### 2.7 Output (`src/result.ts`)
+
+- `createTextResult` wraps any backend payload into MCP `content: [{ type: 'text', text: ... }]`, keeping all tools' return shape consistent.
+
+## 3. Request flow
+
+Typical call (`n2n_create_post`):
+
+1. The tool receives arguments.
+2. Zod schema validation + assertions.
+3. `ContentClient.createPost` is called.
+4. `ContentClient` builds the request and sends it via `HttpTransport.request`.
+5. The response body is parsed and returned.
+6. The tool wraps it with `createTextResult` for the MCP client.
+
+## 4. Key invariants
+
+- Tool contract is stable (nine tools, names, argument semantics).
+- Backend contract is stable (see `docs/BACKEND_API.md`).
+- CLI/deploy entry is stable (`bin` points to `dist/index.js`).
+- Fail-fast error behavior: missing config or invalid arguments error immediately.
+
+## 5. Test boundaries
+
+- `tests/server.test.ts` — all nine tools register.
+- `tests/transport.test.ts` / `tests/client.test.ts` — request-layer behavior of `FetchHttpTransport` and `ContentClient`.
+- `tests/schema.test.ts` — input schemas and `content_scope` format checks.
+
+## 6. Limits and future direction
+
+The design is layered but intentionally a lightweight monolith:
+
+- No runtime retry, idempotency, rate limiting, or backoff.
+- A single error mode (errors are thrown uniformly).
+- Tool capabilities are documented statically.
+
+Possible extensions:
+
+- An `errors.ts` with a unified API error model.
+- Strategic retry / idempotency in the client layer.
+- A service layer (e.g. `PostService`) for richer flows.
+- End-to-end contract tests covering error response shapes.

package/docs/BACKEND_API.md

@@ -0,0 +1,112 @@
+# Backend API Contract
+
+This document defines the HTTP contract that a backend must implement to work with N2N Post2Site. The MCP server connects to this contract through `CONTENT_API_BASE_URL` and `CONTENT_API_KEY`.
+
+## Required endpoints
+
+All endpoints are relative to `CONTENT_API_BASE_URL`.
+
+```http
+GET    /capabilities
+GET    /scopes/{content_scope}
+GET    /posts
+POST   /posts
+GET    /posts/{id_or_slug}
+PATCH  /posts/{id_or_slug}
+POST   /posts/{id_or_slug}/publish
+```
+
+## `GET /capabilities`
+
+Returns the publishing contract for AI clients, including:
+
+- Supported content types.
+- Supported statuses.
+- Supported locales.
+- Single-locale input fields.
+- `content_scope` rules (`content.content_scope`: format, `kinds`, `examples`, `required_for_types`).
+- Available scopes (`scopes`).
+- Safety boundaries.
+
+The MCP server calls this endpoint before every create or update operation.
+
+## `GET /scopes/{content_scope}`
+
+Returns controlled context for a `content_scope` before drafting scoped content.
+
+The body is `content_scope` plus host-defined controlled fields. Common fields:
+
+| Field | Description |
+| --- | --- |
+| `content_scope` | Confirms the valid scope. |
+| `canonical_url` | Page for deeper reading, links, and citations. |
+| `docs_url` | Docs or guide index to prefer for tutorials. |
+| `summary` | Controlled summary. |
+| `key_points` | Controlled facts the assistant may rely on. |
+| `do_not_claim` | Claims the assistant must not make. |
+
+## `GET /posts`
+
+Returns a list of existing posts. Supports filtering by `status`, `type`, `content_scope`, and a search query `q`.
+
+For automated internal linking and search, each post in the list should include:
+
+| Field | Description |
+| --- | --- |
+| `id` | Unique identifier. |
+| `title` | Post title. |
+| `slug` | Unique URL slug. |
+| `link` | Required for AI auto-linking. Absolute public URL of the published post on the live website, so AI clients do not guess paths. |
+
+## `GET /posts/{id_or_slug}`
+
+Returns a single post by ID or slug. The MCP server calls this before updating a post or completing missing locales.
+
+## `POST /posts` and `PATCH /posts/{id_or_slug}`
+
+Create and update calls use one locale per request.
+
+### Payload
+
+```json
+{
+  "slug": "example-product-guide",
+  "type": "guide",
+  "content_scope": "product:example-product",
+  "locale": "en",
+  "title": "How to Use Example Product",
+  "excerpt": "A short guide to using the example product.",
+  "content": "## Overview\n\nMarkdown content..."
+}
+```
+
+### Field rules
+
+- `title` is plain text.
+- `excerpt` is plain text.
+- `content` is Markdown. Inline HTML is allowed when useful. Full HTML documents with `<html>`, `<head>`, or `<body>` are not allowed.
+- `content_scope` is an optional `kind:key` value. The backend requires it for the content types listed in `capabilities.content.content_scope.required_for_types` and prohibits it for all other types.
+- Create and update payloads must not accept `status`, `published_at`, `user_id`, or `author`.
+- Publishing state changes only through `POST /posts/{id_or_slug}/publish`.
+
+### Response conventions
+
+Backends may return `missing_locales` and `next_actions` after create, update, or publish. The MCP server will add missing language versions with additional update calls instead of asking the backend to auto-translate.
+
+## `POST /posts/{id_or_slug}/publish`
+
+Publishes an existing draft. Publishing state is managed exclusively through this endpoint, not through create or update payloads.
+
+## Draft-specific MCP tools
+
+`n2n_list_drafts` and `n2n_update_draft` do not require extra backend endpoints:
+
+- `n2n_list_drafts` calls `GET /posts` with `status=draft`.
+- `n2n_update_draft` calls `GET /posts/{id_or_slug}` first and refuses to continue unless the returned post has `status: "draft"`, then calls `PATCH /posts/{id_or_slug}`.
+
+## Security requirements
+
+- Use a site-scoped API key with the minimum permissions needed.
+- Sanitize backend errors before returning them to the MCP client.
+- Do not expose `user_id`, `author`, `published_at`, or other server-managed fields in create or update payloads.
+- Keep path mapping and field mapping in the backend adapter, not in MCP client configuration.

package/docs/TOOLS_REFERENCE.md

@@ -0,0 +1,142 @@
+# n2n-post2site tools reference
+
+This document describes the MCP tools provided by n2n-post2site. All tools connect to the backend at `CONTENT_API_BASE_URL` and authenticate with `CONTENT_API_KEY`.
+
+See [Backend API Contract](./BACKEND_API.md) for the endpoint specification the backend must implement.
+
+## `n2n_get_capabilities`
+
+Read backend capabilities before creating or updating content.
+
+```json
+{}
+```
+
+The backend returns supported content types, statuses, locales, input fields, `content_scope` rules, and safety boundaries. The MCP server calls this endpoint before every create or update operation.
+
+## `n2n_list_posts`
+
+Search existing posts before drafting new content.
+
+```json
+{
+  "status": "draft",
+  "type": "guide",
+  "content_scope": "product:example-product",
+  "q": "setup guide",
+  "per_page": 20
+}
+```
+
+`status` is a filter only. Do not send `status` in create or update calls.
+
+## `n2n_list_drafts`
+
+List unpublished drafts. This is a draft-only convenience tool over `GET /posts?status=draft`.
+
+```json
+{
+  "type": "guide",
+  "content_scope": "product:example-product",
+  "q": "setup guide",
+  "per_page": 20
+}
+```
+
+## `n2n_get_post`
+
+Read an existing post before updating it, completing missing locales, or writing a follow-up.
+
+```json
+{
+  "id_or_slug": "example-product-guide"
+}
+```
+
+## `n2n_get_scope_context`
+
+Read controlled facts for a `content_scope` before drafting scoped content.
+
+```json
+{
+  "content_scope": "product:example-product"
+}
+```
+
+The backend returns `content_scope` plus host-defined controlled fields, commonly `canonical_url`, `docs_url`, `summary`, `key_points`, and `do_not_claim`.
+
+## `n2n_create_post`
+
+Create a draft. Publishing is a separate step.
+
+Blog post example:
+
+```json
+{
+  "slug": "content-workflow-notes",
+  "type": "technical",
+  "locale": "en",
+  "title": "Content Workflow Notes",
+  "excerpt": "Practical notes from shipping a content workflow.",
+  "content": "## Notes\n\nMarkdown content..."
+}
+```
+
+Scoped content example (a type that requires a content_scope):
+
+```json
+{
+  "slug": "example-product-guide",
+  "type": "guide",
+  "content_scope": "product:example-product",
+  "locale": "en",
+  "title": "How to Use Example Product",
+  "excerpt": "A short guide to using the example product.",
+  "content": "## Overview\n\nMarkdown content..."
+}
+```
+
+## `n2n_update_post`
+
+Update one locale of an existing post. Call `n2n_get_post` first.
+
+```json
+{
+  "id_or_slug": "example-product-guide",
+  "locale": "de",
+  "title": "So verwenden Sie Example Product",
+  "excerpt": "A localized summary for the selected locale.",
+  "content": "## Ueberblick\n\nLocalized Markdown content..."
+}
+```
+
+## `n2n_update_draft`
+
+Update one locale of an unpublished draft. The client reads the post first and refuses to patch unless the backend reports `status: "draft"`.
+
+```json
+{
+  "id_or_slug": "example-product-guide",
+  "locale": "en",
+  "title": "How to Use Example Product",
+  "excerpt": "A refined summary for the draft.",
+  "content": "## Overview\n\nUpdated draft Markdown content..."
+}
+```
+
+## `n2n_publish_post`
+
+Publish an existing draft.
+
+```json
+{
+  "id_or_slug": "example-product-guide"
+}
+```
+
+Publishing state is managed exclusively through this tool, not through create or update payloads.
+
+## Client method mapping
+
+- `ContentClient.listDrafts(input)` calls `GET /posts` with `status=draft` plus the provided list filters.
+- `ContentClient.updateDraft(input)` calls `GET /posts/{id_or_slug}` first, checks `status === "draft"`, then calls `PATCH /posts/{id_or_slug}`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-post2site",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AI-assisted content publishing MCP server for blogs and product guides.",
   "repository": {
     "type": "git",
@@ -31,9 +31,16 @@
   },
   "files": [
     "dist",
+    "assets",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     ".env.example"
   ],
+  "author": "N2NS Lab",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/n2ns"
+  },
   "license": "MIT"
 }