@motiblog/mcp 0.1.1 → 0.1.2

package/README.md

@@ -92,17 +92,18 @@ OAuth lands later — per-project keys are the MVP contract per `docs/product/ag
 
 ## 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.
+Published as [`@motiblog/mcp`](https://www.npmjs.com/package/@motiblog/mcp)
+under the `motiblog` org. Consumers run it with:
 
-Prerequisites, all of which are a human's job:
+```bash
+claude mcp add motiblog --env MOTIBLOG_API_KEY=<key> -- npx -y @motiblog/mcp
+```
 
-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.
+Prerequisites for whoever publishes: membership of the `motiblog` org,
+`npm login`, and **2FA enabled** — npm rejects publishes without it
+(`403 … Two-factor authentication or granular access token with bypass 2fa
+enabled is required`). Either pass `--otp=<code>` or use a granular access
+token with *Bypass 2FA* in `~/.npmrc`.
 
 Then, from `apps/mcp`:
 
@@ -118,7 +119,14 @@ 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:
+Three things that must stay true, and all are easy to break:
+
+- **The `mcp` bin alias.** `npx -y @motiblog/mcp` resolves the bin whose key
+  matches the package's *unscoped* name. Published 0.1.0 had only
+  `motiblog-mcp` and `motiblog-mcp-http`, so the obvious command failed with
+  "could not determine executable to run" — fixed in 0.1.1 by aliasing `mcp`
+  to the stdio entry. Test the bare `npx -y @motiblog/mcp` after any change to
+  `publishConfig.bin`, not just the long form.
 
 - **`@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

package/dist/http.js

@@ -492,7 +492,7 @@ var toolDefinitions = [
     name: "get_digest",
     description: "One-call morning check-in for a project: article counts by lifecycle status, the REVIEW queue (what is waiting to be published, with word counts), posts published in the last 7 days, content plans due in the next 7 days, the latest published post, quota usage, and the project's current autonomy level (L1 = nothing ships without agent review; L2 = clean articles auto-publish). Start every check-in here.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Morning Digest", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const [project, articles, plans] = await Promise.all([
@@ -509,7 +509,7 @@ var toolDefinitions = [
     name: "list_projects",
     description: "List every MotiBlog project the API key can access, with settings that matter to agents: requireApproval (REVIEW vs APPROVED after generation), autoPublish, factCheckStrict, selfHostedBlog, and article quota usage.",
     inputSchema: {},
-    annotations: { readOnlyHint: true },
+    annotations: { title: "List Projects", readOnlyHint: true, destructiveHint: false },
     async handler(_args, ctx) {
       return json(await ctx.client.listProjects());
     }
@@ -518,7 +518,7 @@ var toolDefinitions = [
     name: "get_project",
     description: "Get one MotiBlog project in detail: pipeline settings (aiModel, language, internalLinks, banner), positioning inputs (businessProfile, productTruth, manualPositioning) and quota state.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Project Details", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       return json(await ctx.client.getProject(resolveProjectId(ctx, args.project_id)));
     }
@@ -528,6 +528,7 @@ var toolDefinitions = [
     name: "start_pipeline",
     description: "Start the autonomous pipeline for a project: site crawl/analysis \u2192 topic selection \u2192 article generation for scheduled plans. Returns immediately; poll get_pipeline_status or list_articles(status=GENERATING) to follow progress.",
     inputSchema: { ...projectIdArg },
+    annotations: { title: "Start Content Pipeline", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.pipelineStart(projectId));
@@ -537,7 +538,7 @@ var toolDefinitions = [
     name: "get_pipeline_status",
     description: "Get current pipeline run state for a project: whether a run is active, its steps, and recent run history. Use after start_pipeline or generate_article.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Pipeline Status", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       return json(
         await ctx.client.pipelineStatus(resolveProjectId(ctx, args.project_id))
@@ -552,6 +553,7 @@ var toolDefinitions = [
       topic: import_zod.z.string().min(1).describe('The proposed topic/title, e.g. "How headless CMSs serve AI agents"'),
       ...projectIdArg
     },
+    annotations: { title: "Suggest Topics", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.createContentPlanFromGap(projectId, String(args.topic)));
@@ -561,7 +563,7 @@ var toolDefinitions = [
     name: "list_content_plans",
     description: "List the content plan queue for a project with each entry status: DRAFT (proposed), APPROVED (cleared for generation), IN_PROGRESS, COMPLETED.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "List Content Plans", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       return json(await ctx.client.listContentPlans(resolveProjectId(ctx, args.project_id)));
     }
@@ -573,6 +575,7 @@ var toolDefinitions = [
       plan_id: import_zod.z.string().describe("Content plan entry id (from list_content_plans)"),
       ...projectIdArg
     },
+    annotations: { title: "Approve Content Plan", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.approveContentPlan(projectId, String(args.plan_id)));
@@ -585,6 +588,7 @@ var toolDefinitions = [
       plan_id: import_zod.z.string().describe("Content plan entry id"),
       ...projectIdArg
     },
+    annotations: { title: "Regenerate Content Plan", readOnlyHint: false, destructiveHint: true },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.regenerateContentPlan(projectId, String(args.plan_id)));
@@ -597,6 +601,7 @@ var toolDefinitions = [
       plan_id: import_zod.z.string().describe("Content plan entry id (must be APPROVED)"),
       ...projectIdArg
     },
+    annotations: { title: "Generate Article", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.generateArticleFromPlan(projectId, String(args.plan_id)));
@@ -610,7 +615,7 @@ var toolDefinitions = [
       end_date: import_zod.z.string().describe("ISO date, e.g. 2026-09-30"),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Content Calendar", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -630,7 +635,7 @@ var toolDefinitions = [
       status: import_zod.z.enum(ARTICLE_STATUSES).optional().describe("Filter by lifecycle status (default REVIEW)"),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Review Queue", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const status = typeof args.status === "string" ? args.status : "REVIEW";
@@ -646,7 +651,7 @@ var toolDefinitions = [
       include_logs: import_zod.z.boolean().optional().describe("Include pipeline phase logs (default false)"),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Get Article", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const article = await ctx.client.getArticle(projectId, String(args.article_id));
@@ -668,6 +673,7 @@ var toolDefinitions = [
       status: import_zod.z.enum(["DRAFT", "REVIEW", "APPROVED"]).optional(),
       ...projectIdArg
     },
+    annotations: { title: "Update Article", readOnlyHint: false, destructiveHint: true },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const patch = {};
@@ -686,6 +692,12 @@ var toolDefinitions = [
       publish_now: import_zod.z.boolean().optional().describe("Also trigger publishing now (default false)"),
       ...projectIdArg
     },
+    annotations: {
+      title: "Approve & Publish",
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const articleId = String(args.article_id);
@@ -704,6 +716,7 @@ var toolDefinitions = [
       clear_schedule: import_zod.z.boolean().optional().describe("Clear any scheduled date instead of setting one"),
       ...projectIdArg
     },
+    annotations: { title: "Schedule Publication", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const value = args.clear_schedule === true ? null : args.scheduled_for ?? null;
@@ -718,7 +731,7 @@ var toolDefinitions = [
       article_id: import_zod.z.string().describe("Article id"),
       ...projectIdArg
     },
-    annotations: { destructiveHint: true },
+    annotations: { title: "Regenerate Article", readOnlyHint: false, destructiveHint: true },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.regenerateArticle(projectId, String(args.article_id)));
@@ -732,6 +745,7 @@ var toolDefinitions = [
       chapter_index: import_zod.z.number().int().min(0).describe("Zero-based chapter index"),
       ...projectIdArg
     },
+    annotations: { title: "Regenerate Chapter", readOnlyHint: false, destructiveHint: true },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -750,7 +764,7 @@ var toolDefinitions = [
       article_id: import_zod.z.string().describe("Article id"),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Pipeline Logs", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(await ctx.client.getPipelineLogs(projectId, String(args.article_id)));
@@ -760,7 +774,7 @@ var toolDefinitions = [
     name: "list_refresh_suggestions",
     description: "Across ALL your projects: published articles whose Search Console stats suggest they are decaying and would benefit from a refresh. Feed these back into planning via suggest_topics or update_article.",
     inputSchema: {},
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Refresh Suggestions", readOnlyHint: true, destructiveHint: false },
     async handler(_args, ctx) {
       return json(await ctx.client.listRefreshSuggestions());
     }
@@ -770,7 +784,7 @@ var toolDefinitions = [
     name: "list_integrations",
     description: "List configured publishing targets (integrations) for a project: WEBHOOK, WORDPRESS, GHOST, WEBFLOW, SHOPIFY, DEVTO, SANITY, CUSTOM_API \u2014 with enabled state.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "List Integrations", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const integrations = await ctx.client.listIntegrations(projectId);
@@ -787,6 +801,12 @@ var toolDefinitions = [
       method: import_zod.z.enum(["POST", "PUT", "PATCH"]).optional().describe("HTTP method (default POST)"),
       ...projectIdArg
     },
+    annotations: {
+      title: "Create Webhook Integration",
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const config = { url: String(args.url) };
@@ -810,6 +830,12 @@ var toolDefinitions = [
       mode: import_zod.z.enum(["ping", "full"]).optional(),
       ...projectIdArg
     },
+    annotations: {
+      title: "Test Integration",
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -829,6 +855,12 @@ var toolDefinitions = [
       integration_id: import_zod.z.string().describe("Target integration id"),
       ...projectIdArg
     },
+    annotations: {
+      title: "Publish to CMS",
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -848,6 +880,12 @@ var toolDefinitions = [
       integration_id: import_zod.z.string(),
       ...projectIdArg
     },
+    annotations: {
+      title: "Retry Publish",
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -867,7 +905,7 @@ var toolDefinitions = [
       limit: import_zod.z.number().int().min(1).max(200).optional(),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Publish Logs", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -884,7 +922,7 @@ var toolDefinitions = [
     name: "list_keywords",
     description: "List tracked keywords for a project (search volume, difficulty, intent, status). Keywords drive topic relevance in generation.",
     inputSchema: { ...projectIdArg },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "List Keywords", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       return json(await ctx.client.listKeywords(resolveProjectId(ctx, args.project_id)));
     }
@@ -899,6 +937,7 @@ var toolDefinitions = [
       intent: import_zod.z.enum(["INFORMATIONAL", "NAVIGATIONAL", "TRANSACTIONAL", "COMMERCIAL"]).optional(),
       ...projectIdArg
     },
+    annotations: { title: "Add Keyword", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -918,7 +957,7 @@ var toolDefinitions = [
       active_only: import_zod.z.boolean().optional().describe("Only active facts (default false = all)"),
       ...projectIdArg
     },
-    annotations: { readOnlyHint: true },
+    annotations: { title: "List Product Facts", readOnlyHint: true, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       return json(
@@ -936,6 +975,7 @@ var toolDefinitions = [
       active: import_zod.z.boolean().optional().describe("Set active flag when updating"),
       ...projectIdArg
     },
+    annotations: { title: "Supply Product Fact", readOnlyHint: false, destructiveHint: false },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const category = Array.isArray(args.category) ? args.category.map(String) : void 0;
@@ -966,6 +1006,12 @@ var toolDefinitions = [
       limit: import_zod.z.number().int().min(1).max(500).optional().describe("Max articles to export (default 100)"),
       ...projectIdArg
     },
+    annotations: {
+      title: "Export Blog to Files",
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true
+    },
     async handler(args, ctx) {
       const projectId = resolveProjectId(ctx, args.project_id);
       const status = typeof args.status === "string" ? args.status : "PUBLISHED";
@@ -1002,10 +1048,12 @@ function buildServer(config) {
     register(
       tool.name,
       {
-        title: tool.name,
+        // The human-readable title, not the wire name — a picker showing
+        // "approve_publication" tells a person nothing about what it does.
+        title: tool.annotations.title,
         description: tool.description,
         inputSchema: tool.inputSchema,
-        ...tool.annotations ? { annotations: tool.annotations } : {}
+        annotations: tool.annotations
       },
       async (args) => {
         let result;