n2n-post2site 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,9 +4,19 @@ All notable changes to N2N Post2Site are documented in this file.
 
 ## Unreleased
 
-### Added
+## [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
 
-- None yet.
+- 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
 

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

@@ -4,14 +4,13 @@
 
 # n2n-post2site
 
-AI-assisted content publishing MCP server for blogs and product guides.
+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)
 
 ---
 
@@ -19,28 +18,70 @@ AI-assisted content publishing MCP server for blogs and product guides.
 
 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.
 
+## 📚 Contents
+
+- [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)
+
 ## 💡 What is n2n-post2site?
 
 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 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 │
+└─────────────────────────────┘
+```
+
+- **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`.
+
+See [Architecture](./docs/ARCHITECTURE.md) for the full layer breakdown.
+
 ## 📰 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. Resume unfinished work with `n2n_list_drafts`, `n2n_get_post`, and `n2n_update_draft`.
 6. Review the draft.
@@ -50,6 +91,8 @@ The assistant should follow this workflow:
 
 **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).
 
+> **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.
+
 ### 1. Configure your MCP client
 
 Using the npm package:
@@ -99,9 +142,9 @@ See **[Backend API Contract](./docs/BACKEND_API.md)** for the full specification
 
 ## 🛠️ MCP tools
 
-- **Discovery**: read backend capabilities, list existing posts, and load product context before drafting.
-- **Drafting**: create posts, update posts one locale at a time, and resume unpublished drafts.
-- **Publishing**: publish an approved draft through an explicit publish step.
+- **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.
 
 See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
@@ -159,4 +202,4 @@ This project is licensed under the [MIT License](./LICENSE).
 
 ---
 
-Built by [N2NS Lab](https://n2ns.com), the open-source lab of [datafrog.io](https://datafrog.io) for practical AI developer tools.
+Built by [N2NS Lab](https://n2ns.com), an open-source lab for practical AI developer tools.

package/dist/content-client.js

@@ -1,7 +1,7 @@
 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;
     transport;
@@ -29,8 +29,8 @@ export class ContentClient {
     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, {

package/dist/schemas/blog-post.js

@@ -1,27 +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.'),
@@ -32,16 +31,13 @@ export const updatePostSchema = createPostSchema.partial().extend({
 });
 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

@@ -3,7 +3,7 @@ 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 { registerGetProductContextTool } from './tools/get-product-context.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';
@@ -19,7 +19,7 @@ export function createServer(config) {
     registerListPostsTool(server, client);
     registerListDraftsTool(server, client);
     registerGetPostTool(server, client);
-    registerGetProductContextTool(server, client);
+    registerGetScopeContextTool(server, client);
     registerCreatePostTool(server, client);
     registerUpdatePostTool(server, client);
     registerUpdateDraftTool(server, client);

package/dist/tools/create-post.js

@@ -1,9 +1,9 @@
 import { createTextResult } from '../result.js';
-import { assertContentPostShape, createPostSchema } from '../schemas/blog-post.js';
+import { assertContentScopeFormat, createPostSchema } from '../schemas/blog-post.js';
 export function registerCreatePostTool(server, client) {
-    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) => {
+    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);
-        assertContentPostShape(parsed);
+        assertContentScopeFormat(parsed.content_scope);
         const result = await client.createPost(parsed);
         return createTextResult(result);
     });

package/dist/tools/get-capabilities.js

@@ -1,7 +1,7 @@
 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, and product guide scopes.', capabilitiesSchema.shape, async (input) => {
+    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-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

@@ -1,7 +1,7 @@
 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 articles or product guides. 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) => {
+    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

@@ -1,7 +1,7 @@
 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 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) => {
+    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/update-draft.js

@@ -1,9 +1,9 @@
 import { createTextResult } from '../result.js';
-import { assertContentPostShape, updateDraftSchema } from '../schemas/blog-post.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);
-        assertContentPostShape(parsed);
+        assertContentScopeFormat(parsed.content_scope);
         const result = await client.updateDraft(parsed);
         return createTextResult(result);
     });

package/dist/tools/update-post.js

@@ -1,9 +1,9 @@
 import { createTextResult } from '../result.js';
-import { assertContentPostShape, updatePostSchema } from '../schemas/blog-post.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);
-        assertContentPostShape(parsed);
+        assertContentScopeFormat(parsed.content_scope);
         const result = await client.updatePost(parsed);
         return createTextResult(result);
     });

package/docs/ARCHITECTURE.md

@@ -1,127 +1,113 @@
-# N2N Post2Site 架构说明（v0.1.2）
+# N2N Post2Site Architecture
 
-本文档说明 `n2n-post2site` 当前架构，目标是约束边界、保留接口兼容，并让后续改动有稳定接入点。
+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. 系统定位
+## 1. What it is
 
-`n2n-post2site` 是 MCP server，作用是：
+`n2n-post2site` is an MCP server. It:
 
-- 解析环境变量并创建 MCP Server 实例。
-- 向 MCP 客户端暴露 9 个内容发布工具。
-- 将工具参数转为对后端内容 API 的 HTTP 调用。
-- 将后端返回值统一封装为 MCP 可展示文本。
+- 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.
 
-它本身不承载持久化、权限管理、审核策略或内容排序决策；这些都应由后端 API 提供方实现。
+It does not own persistence, authorization, review policy, or content-ranking decisions. Those belong to the backend API provider.
 
-## 2. 分层结构
+## 2. Layers
 
-### 2.1 运行入口层（`src/index.ts`）
+### 2.1 Entry (`src/index.ts`)
 
-- 使用 `createServer(loadConfig())` 创建 MCP 实例。
-- 使用 `StdioServerTransport` 与 MCP 客户端通信。
-- 仅负责进程生命周期与失败输出。
+- Creates the server via `createServer(loadConfig())`.
+- Connects to the MCP client over `StdioServerTransport`.
+- Owns only process lifecycle and failure output.
 
-### 2.2 配置层（`src/config.ts`）
+### 2.2 Configuration (`src/config.ts`)
 
-- 读取环境变量：
-  - `CONTENT_API_BASE_URL`
-  - `CONTENT_API_KEY`
-- 校验缺失字段并报错。
-- 统一清理 `CONTENT_API_BASE_URL` 末尾斜杠。
+- Reads `CONTENT_API_BASE_URL` and `CONTENT_API_KEY`.
+- Fails fast on missing values.
+- Normalizes trailing slashes on `CONTENT_API_BASE_URL`.
 
-### 2.3 组装层（`src/server.ts`）
+### 2.3 Assembly (`src/server.ts`)
 
-- 只做“构建与注册”职责：
-  1. 构造 `ContentClient`
-  2. 新建 `McpServer`
-  3. 注册 9 个工具
+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_product_context`
+- `n2n_get_scope_context`
 - `n2n_create_post`
 - `n2n_update_post`
 - `n2n_update_draft`
 - `n2n_publish_post`
 
-### 2.4 工具层（`src/tools/*.ts`）
+### 2.4 Tools (`src/tools/*.ts`)
 
-每个文件对应一个 MCP tool：
+Each file is one MCP tool:
 
-- 参数校验（Zod schema + 业务约束断言）
-- 调用 `ContentClient` 对应方法
-- 返回统一 `text` 结果
+- Validate input (Zod schema + lightweight assertions).
+- Call the matching `ContentClient` method.
+- Return a uniform `text` result.
 
-工具层职责不包含底层 HTTP、请求头、JSON 解析或路由拼接。
+Tools do not deal with low-level HTTP, headers, JSON parsing, or path building.
 
-### 2.5 传输与客户端层
+### 2.5 Transport and client
 
-- `src/transport/http.ts`
-  - `HttpTransport` 接口
-  - 默认 `FetchHttpTransport` 封装 `fetch`
-  - 负责响应解析（JSON / text）、状态透传
+- `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}`
 
-- `src/content-client.ts`
-  - 统一拼装路径与 HTTP 方法
-  - 注入鉴权头（`X-API-KEY` / `Authorization`）
-  - 统一处理非 2xx 报错为异常
-  - 聚合列表参数与路由参数
-  - 实现 `updateDraft` 的业务校验流程：
-    1. 先调用 `GET /posts/{id_or_slug}`
-    2. 校验 `status === 'draft'`
-    3. 才允许 `PATCH /posts/{id_or_slug}`
+### 2.6 Schemas and validation (`src/schemas/blog-post.ts`)
 
-### 2.6 模型与约束层（`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`).
 
-- Zod schema 定义所有工具输入约束。
-- `assertContentPostShape` 强化 `type/content_scope` 规则：
-  - `type=guide` 必须带 `content_scope`
-  - 非 guide 不允许带 `content_scope`
-  - `content_scope` 格式必须是 `kind:key`
+### 2.7 Output (`src/result.ts`)
 
-### 2.7 输出层（`src/result.ts`）
+- `createTextResult` wraps any backend payload into MCP `content: [{ type: 'text', text: ... }]`, keeping all tools' return shape consistent.
 
-- 用 `createTextResult` 将任意后端返回内容转为 MCP `content: [{type:'text', text:...}]`。
-- 维持了所有工具一致的返回格式。
+## 3. Request flow
 
-## 3. 请求流
+Typical call (`n2n_create_post`):
 
-典型调用流（`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.
 
-1. MCP 工具接收参数
-2. Zod schema 校验 + 业务断言
-3. 调用 `ContentClient.createPost`
-4. `ContentClient` 构造请求并通过 `HttpTransport.request` 发起 HTTP
-5. 解析响应体并返回
-6. 工具层用 `createTextResult` 包装并返回给 MCP
+## 4. Key invariants
 
-## 4. 关键不变式
+- 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.
 
-- 工具契约不变（9 个工具 + 名称 + 入参语义）
-- 后端接口契约不变（见 `docs/BACKEND_API.md`）
-- CLI/部署接口不变（`bin` 指向 `dist/index.js`）
-- 错误行为保持“尽早失败”：缺少配置或非法参数立即报错
+## 5. Test boundaries
 
-## 5. 测试边界
+- `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.
 
-- `tests/server.test.ts`：保证 9 个工具完整注册。
-- `tests/transport.test.ts`：验证 `FetchHttpTransport` 和 `ContentClient` 的请求层行为。
+## 6. Limits and future direction
 
-## 6. 当前架构限制与改造方向
+The design is layered but intentionally a lightweight monolith:
 
-当前设计有清晰分层，但仍是“轻量单体” MCP server：
+- No runtime retry, idempotency, rate limiting, or backoff.
+- A single error mode (errors are thrown uniformly).
+- Tool capabilities are documented statically.
 
-- 无运行时重试、幂等保护、限流和退避策略
-- 无完整错误分类体系（目前统一抛错）
-- 工具能力说明仍以静态文档描述为主
+Possible extensions:
 
-后续可扩展点：
-
-- 新增 `errors.ts` 统一 API 错误模型
-- 在客户端层引入策略性重试/幂等
-- 引入服务层（如 `PostService`）汇聚更复杂业务流
-- 添加端到端契约测试覆盖错误返回形态
+- 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

@@ -8,7 +8,7 @@ All endpoints are relative to `CONTENT_API_BASE_URL`.
 
 ```http
 GET    /capabilities
-GET    /products/{content_scope}
+GET    /scopes/{content_scope}
 GET    /posts
 POST   /posts
 GET    /posts/{id_or_slug}
@@ -24,24 +24,24 @@ Returns the publishing contract for AI clients, including:
 - Supported statuses.
 - Supported locales.
 - Single-locale input fields.
-- `content_scope` rules.
-- Available product guide scopes.
+- `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 /products/{content_scope}`
+## `GET /scopes/{content_scope}`
 
-Returns controlled product context before drafting product guides.
+Returns controlled context for a `content_scope` before drafting scoped content.
 
-Expected response fields:
+The body is `content_scope` plus host-defined controlled fields. Common fields:
 
 | Field | Description |
 | --- | --- |
-| `content_scope` | Confirms the valid product guide scope. |
-| `canonical_url` | Product page for deeper reading, links, and citations. |
+| `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 product summary. |
+| `summary` | Controlled summary. |
 | `key_points` | Controlled facts the assistant may rely on. |
 | `do_not_claim` | Claims the assistant must not make. |
 
@@ -85,6 +85,7 @@ Create and update calls use one locale per request.
 - `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`.
 

package/docs/TOOLS_REFERENCE.md

@@ -53,9 +53,9 @@ Read an existing post before updating it, completing missing locales, or writing
 }
 ```
 
-## `n2n_get_product_context`
+## `n2n_get_scope_context`
 
-Read controlled product facts before drafting a product guide.
+Read controlled facts for a `content_scope` before drafting scoped content.
 
 ```json
 {
@@ -63,13 +63,13 @@ Read controlled product facts before drafting a product guide.
 }
 ```
 
-The backend returns: `content_scope`, `canonical_url`, `docs_url`, `summary`, `key_points`, and `do_not_claim`.
+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.
 
-Company blog example:
+Blog post example:
 
 ```json
 {
@@ -82,7 +82,7 @@ Company blog example:
 }
 ```
 
-Product guide example:
+Scoped content example (a type that requires a content_scope):
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-post2site",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "AI-assisted content publishing MCP server for blogs and product guides.",
   "repository": {
     "type": "git",

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

@@ -1,10 +0,0 @@
-import { createTextResult } from '../result.js';
-import { assertContentPostShape, productContextSchema } from '../schemas/blog-post.js';
-export function registerGetProductContextTool(server, client) {
-    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 createTextResult(result);
-    });
-}

package/docs/REFACTOR_PLAN.md

@@ -1,152 +0,0 @@
-# N2N Post2Site 重构过程文档（v0.1.x 结构化解耦改造）
-
-> 目标：保持对外行为不变，先把模块拆分和职责边界补齐，为后续特性（如动态能力适配）做底座，降低耦合、提高可测试性与可维护性。
-
-## 1. 背景与动机
-
-当前实现中，`src/index.ts` 承担了以下过多职责：
-
-- MCP 工具注册
-- 参数校验与业务流编排
-- HTTP 客户端调用
-- 响应封装
-
-`src/content-client.ts` 中也同时承担了请求构建、鉴权、错误处理与状态校验。现有规模虽小，但未来增加能力动态化、重试、错误分类时会迅速耦合。
-
-本次改造目标是把耦合点拆开，不新增或变更外部 API 语义。
-
-## 2. 改造原则（硬约束）
-
-1. 不改变 MCP 工具的调用输入/输出行为。
-2. 不改变后端 Content API 的调用契约。
-3. 不改变命令行入口、环境变量和发布产物协议。
-4. 每个新模块应单一职责，文件改动最小且可回滚。
-5. 保留现有测试覆盖语义；先保证现有测试通过（`npm run check`）。
-
-## 3. 现状结构（重构前）
-
-- `src/index.ts`
-  - 启动 MCP 服务器
-  - 注册全部 9 个工具
-  - 工具内联处理 request/parse/result 输出
-- `src/content-client.ts`
-  - 直接构建并发送 `fetch`
-  - 鉴权头、错误处理、JSON 解析集中在同一类
-  - 状态校验（`updateDraft`）也在此处理
-- `src/schemas/blog-post.ts`
-  - 参数 schema 与运行时断言集中定义
-- `src/tools/`
-  - 每个 MCP 工具已拆到独立文件：`get-capabilities.ts`, `list-posts.ts`, `list-drafts.ts`, `get-post.ts`, `get-product-context.ts`, `create-post.ts`, `update-post.ts`, `update-draft.ts`, `publish-post.ts`
-
-## 4. 目标结构（重构后）
-
-目标是引入以下边界：
-
-- `src/server.ts`：仅负责 MCP Server 的实例化与工具注册（`index.ts` 作为入口）。
-- `src/tools/*Tool.ts`：每个 MCP 工具单文件（`get-capabilities.ts`, `list-posts.ts`, `list-drafts.ts`, `get-post.ts`, `get-product-context.ts`, `create-post.ts`, `update-post.ts`, `update-draft.ts`, `publish-post.ts`）。
-- `src/services/`
-  - `posts.ts`（可选）：封装 `updateDraft` 这类业务流（“读当前状态→校验→更新”）。
-  - 后续扩展点：发布、列表拼装、策略判断。
-- `src/transport/http.ts`
-  - `HttpTransport` 抽象与默认实现（`fetch` 封装）。
-  - 统一注入 `X-API-KEY`、`Authorization`、`Content-Type`。
-- `src/result.ts`
-  - 统一 MCP 文本结果格式。
-- `src/errors.ts`（可选）
-  - 自定义 API 错误对象（携带 endpoint、method、status、body）。
-- `src/types/`
-  - 放置会被服务层复用的公共类型（可选）。
-
-> 说明：`src/tools` 目录已存在，可直接使用，先按最小重构只做当前 9 个工具文件即可。
-
-## 5. 具体实施步骤
-
-### 阶段 1：执行层切分（最低风险）
-
-1. 新建 `src/result.ts`，抽离 `textResult()`。
-2. 新建 `src/transport/http.ts` 与 `HttpTransport` 接口。
-3. 重构 `ContentClient` 使用 transport 注入，去掉直接 `fetch` 依赖。
-4. 拆出 `src/server.ts`，让 `index.ts` 只做启动与异常出口。
-
-验收标准：
-
-- 行为不变（工具响应 JSON 字符串包装不变）。
-- `npm run check` 通过。
-
-### 阶段 2：工具拆文件（中等改动）
-
-1. 为每个 MCP tool 在 `src/tools/` 下新建处理模块。
-2. 每个模块只做：参数校验 + 对应 service/client 调用 + 返回统一 result。
-3. 将重复文案字符串逐步提取到常量（非强制）。
-
-验收标准：
-
-- `n2n_get_capabilities` 到 `n2n_publish_post` 全部可从新模块注册。
-- 与现有功能的可见行为一致。
-
-### 阶段 3：服务层与业务流集中化（可选但推荐）
-
-1. 将 `updateDraft` 中的“先拉取状态再 PATCH”的状态策略移动到 `posts.ts` 服务。
-2. 为未来新增业务动作预留 `PostService`。
-
-验收标准：
-
-- `updateDraft` 流程不变（仍拒绝非 draft）
-- `tests/client.test.ts` 中的行为断言可保持通过。
-
-### 阶段 4：文档与追踪更新
-
-1. 在本文件补充阶段完成记录。
-2. 可选地更新 `ROADMAP.md`，若该改造需要对外公开发布说明。
-3. 更新 `CHANGELOG.md`（若版本号/可见改动需要记录）。
-4. 如有新增文件夹，更新仓库文档索引（README 中可选）。
-
-> 当前执行状态：阶段 1~2 已完成；阶段 3 作为可选项保留；阶段 4 文档补充已完成（结构变更说明已更新，本次未更新 `ROADMAP.md`/`CHANGELOG.md`）。
-
-验收标准：
-
-- 代码和文档结构一致。
-- 未引入新外部行为依赖。
-
-## 6. 回滚策略
-
-- 所有改造分批提交（每个阶段单独 commit），遇到风险可回退最近提交。
-- 每次提交前保留 `main` 分支上的行为对照：通过 `npm run check` 作为门槛。
-- 不在功能层更改任何 schema/接口时，回滚风险低。
-
-## 7. 风险与对策
-
-1. **工具描述文字重复**
-   - 风险：文本变更导致行为认知差异
-   - 对策：保持文本不变；仅抽象常量。
-2. **测试脆弱性上升**
-   - 风险：拆分后导入路径变化导致 mock 失败
-   - 对策：保留现有 public 行为与导入边界，测试逐项执行通过。
-3. **过度重构（scope creep）**
-   - 风险：把未要求的能力（动态能力发现）一起引入
-   - 对策：本次只做解耦，不新增 schema 或协议。
-
-## 8. 交付定义（Acceptance）
-
-- `npm run check` 通过。
-- 工具行为回归对照未变：
-  - 发布流程
-  - 草稿状态检查
-  - 产品上下文读取
-- 不引入新的运行时依赖。
-- 不修改后端契约字段。
-
-## 9. 里程碑时间建议（可选）
-
-- 第一天：阶段 1~2（核心结构搭建）
-- 第一天：阶段 3~4（文档与清理）
-- 第二天：`npm run check` 与 smoke 验证（手工 1 次端到端）
-
-## 10. 变更边界声明
-
-本次方案不覆盖以下内容：
-
-- 动态能力驱动 schema（这是 `ROADMAP` 中 v0.2 规划项）。
-- 发布 API 新增功能。
-- 新增工具。
-- 后端能力模型扩展。