@kieksme/mcp-hashnode 1.1.0

package/README.md

@@ -0,0 +1,187 @@
+# @kieksme/mcp-hashnode
+
+[![npm version](https://img.shields.io/npm/v/%40kieksme%2Fmcp-hashnode)](https://www.npmjs.com/package/@kieksme/mcp-hashnode)
+[![Release](https://github.com/kieksme/mcp-hashnode/actions/workflows/release.yml/badge.svg)](https://github.com/kieksme/mcp-hashnode/actions/workflows/release.yml)
+
+MCP server for the [Hashnode](https://hashnode.com) GraphQL API.  
+Create drafts, publish posts, manage your blog — all via Claude.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `hashnode_get_me` | Get your profile and publication IDs |
+| `hashnode_get_publication` | Get publication info by host |
+| `hashnode_list_posts` | List published posts |
+| `hashnode_get_post` | Get a single post by slug |
+| `hashnode_create_draft` | Create a draft |
+| `hashnode_update_draft` | Update an existing draft |
+| `hashnode_list_drafts` | List drafts in a publication |
+| `hashnode_publish_draft` | Publish a draft → live post |
+| `hashnode_publish_post` | Publish directly (no draft step) |
+| `hashnode_update_post` | Update a published post |
+| `hashnode_delete_post` | Delete a post ⚠️ |
+
+## Setup
+
+### 1. Get your Personal Access Token
+
+Go to [hashnode.com/settings/developer](https://hashnode.com/settings/developer) and click **Generate new token**.
+
+### 2. Install
+
+**Via npx (no install needed — recommended):**
+```bash
+npx -y @kieksme/mcp-hashnode
+```
+
+**Via global install:**
+```bash
+pnpm add -g @kieksme/mcp-hashnode
+```
+
+**Build from source:**
+```bash
+git clone https://github.com/kieksme/mcp-hashnode.git
+cd mcp-hashnode
+pnpm install && pnpm run build
+```
+
+### 3. Configure your MCP client
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "hashnode": {
+      "command": "npx",
+      "args": ["-y", "@kieksme/mcp-hashnode"],
+      "env": {
+        "HASHNODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code (CLI)
+
+```bash
+claude mcp add hashnode \
+  --command npx \
+  --args "-y @kieksme/mcp-hashnode" \
+  --env HASHNODE_TOKEN=your-token-here
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project root, or to `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "hashnode": {
+      "command": "npx",
+      "args": ["-y", "@kieksme/mcp-hashnode"],
+      "env": {
+        "HASHNODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+#### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "hashnode": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@kieksme/mcp-hashnode"],
+      "env": {
+        "HASHNODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hashnode": {
+      "command": "npx",
+      "args": ["-y", "@kieksme/mcp-hashnode"],
+      "env": {
+        "HASHNODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Usage examples
+
+```
+"What's my publication ID?"
+→ hashnode_get_me
+
+"Create a draft called 'Cloud Security Best Practices' with this content: ..."
+→ hashnode_create_draft
+
+"Publish the draft with ID xyz"
+→ hashnode_publish_draft
+
+"List my last 10 posts on thinkport.hashnode.dev"
+→ hashnode_list_posts
+```
+
+## Authentication
+
+Hashnode requires `Authorization: <token>` (no `Bearer` prefix).  
+All mutations need the token; most read queries are public.
+
+## Rate limits
+
+- Queries: 20,000 req/min  
+- Mutations: 500 req/min
+
+## Tags format
+
+Tags must be objects — not plain strings:
+
+```json
+[
+  { "name": "Cloud Computing", "slug": "cloud-computing" },
+  { "name": "DevOps", "slug": "devops" }
+]
+```
+
+## Releases
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated releases.
+
+- Commits to `main` that follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:` etc.) are tracked automatically.
+- All supported Conventional Commit categories (`feat`, `fix`, `perf`, `revert`, `docs`, `style`, `chore`, `refactor`, `test`, `build`, `ci`) are included for release-please changelog generation and Release PR updates.
+- release-please opens a **Release PR** that bumps the version and updates `CHANGELOG.md`.
+- Merging the Release PR creates a **GitHub Release** and triggers an automated **npm publish**.
+
+### Required secret
+
+Add `NPM_TOKEN` to the repository secrets (**Settings → Secrets → Actions**):  
+Generate at [npmjs.com/settings/tokens](https://www.npmjs.com/settings/tokens) — choose **Automation** type.
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const HASHNODE_GQL_ENDPOINT = "https://gql.hashnode.com";
+export declare const CHARACTER_LIMIT = 25000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,6BAA6B,CAAC;AAChE,eAAO,MAAM,eAAe,QAAQ,CAAC"}

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const HASHNODE_GQL_ENDPOINT = "https://gql.hashnode.com";
+export const CHARACTER_LIMIT = 25000;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAChE,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * @kieksme/mcp-hashnode
+ *
+ * MCP server for the Hashnode GraphQL API.
+ * Supports creating drafts, publishing posts, listing/updating/deleting posts,
+ * and querying publications.
+ *
+ * Required env var: HASHNODE_TOKEN  (Personal Access Token from hashnode.com/settings/developer)
+ *
+ * Usage (stdio):
+ *   HASHNODE_TOKEN=<token> node dist/index.js
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * @kieksme/mcp-hashnode
+ *
+ * MCP server for the Hashnode GraphQL API.
+ * Supports creating drafts, publishing posts, listing/updating/deleting posts,
+ * and querying publications.
+ *
+ * Required env var: HASHNODE_TOKEN  (Personal Access Token from hashnode.com/settings/developer)
+ *
+ * Usage (stdio):
+ *   HASHNODE_TOKEN=<token> node dist/index.js
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { setApiToken } from "./services/hashnode.js";
+import { registerPublicationTools } from "./tools/publications.js";
+import { registerDraftTools } from "./tools/drafts.js";
+import { registerPostTools } from "./tools/posts.js";
+// ─── Bootstrap ────────────────────────────────────────────────────────────────
+const token = process.env.HASHNODE_TOKEN;
+if (!token) {
+    console.error("ERROR: HASHNODE_TOKEN environment variable is required.\n" +
+        "       Get your Personal Access Token at https://hashnode.com/settings/developer");
+    process.exit(1);
+}
+setApiToken(token);
+// ─── Server ───────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "@kieksme/mcp-hashnode",
+    version: "1.0.0",
+});
+registerPublicationTools(server);
+registerDraftTools(server);
+registerPostTools(server);
+// ─── Transport ────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("@kieksme/mcp-hashnode running via stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iFAAiF;AAEjF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AACzC,IAAI,CAAC,KAAK,EAAE,CAAC;IACX,OAAO,CAAC,KAAK,CACX,2DAA2D;QACzD,kFAAkF,CACrF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,WAAW,CAAC,KAAK,CAAC,CAAC;AAEnB,iFAAiF;AAEjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE1B,iFAAiF;AAEjF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC3D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CACX,eAAe,EACf,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/services/hashnode.d.ts

@@ -0,0 +1,9 @@
+export declare function setApiToken(token: string): void;
+/**
+ * Execute a GraphQL query or mutation against the Hashnode API.
+ * Auth header format: `Authorization: <token>` (NOT Bearer).
+ */
+export declare function gql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+/** Convert axios / GraphQL errors into actionable messages. */
+export declare function normalizeError(error: unknown): Error;
+//# sourceMappingURL=hashnode.d.ts.map

package/dist/services/hashnode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashnode.d.ts","sourceRoot":"","sources":["../../src/services/hashnode.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;GAGG;AACH,wBAAsB,GAAG,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAiCZ;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CA6BpD"}

package/dist/services/hashnode.js

@@ -0,0 +1,61 @@
+import axios, { AxiosError } from "axios";
+import { HASHNODE_GQL_ENDPOINT } from "../constants.js";
+let apiToken;
+export function setApiToken(token) {
+    apiToken = token;
+}
+/**
+ * Execute a GraphQL query or mutation against the Hashnode API.
+ * Auth header format: `Authorization: <token>` (NOT Bearer).
+ */
+export async function gql(query, variables) {
+    if (!apiToken) {
+        throw new Error("HASHNODE_TOKEN environment variable is not set. " +
+            "Get your Personal Access Token at https://hashnode.com/settings/developer");
+    }
+    try {
+        const response = await axios.post(HASHNODE_GQL_ENDPOINT, { query, variables }, {
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                Authorization: apiToken,
+            },
+            timeout: 30_000,
+        });
+        if (response.data.errors?.length) {
+            const msgs = response.data.errors
+                .map((e) => e.message)
+                .join("; ");
+            throw new Error(`GraphQL error: ${msgs}`);
+        }
+        return response.data.data;
+    }
+    catch (error) {
+        throw normalizeError(error);
+    }
+}
+/** Convert axios / GraphQL errors into actionable messages. */
+export function normalizeError(error) {
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            switch (error.response.status) {
+                case 401:
+                    return new Error("Error: Invalid or missing Hashnode token. " +
+                        "Generate one at https://hashnode.com/settings/developer");
+                case 403:
+                    return new Error("Error: Permission denied. Make sure your token has write access.");
+                case 429:
+                    return new Error("Error: Rate limit exceeded (500 mutations/min). Please wait and retry.");
+                default:
+                    return new Error(`Error: Hashnode API returned HTTP ${error.response.status}`);
+            }
+        }
+        if (error.code === "ECONNABORTED") {
+            return new Error("Error: Request timed out. Please try again.");
+        }
+    }
+    if (error instanceof Error)
+        return error;
+    return new Error(`Error: ${String(error)}`);
+}
+//# sourceMappingURL=hashnode.js.map

package/dist/services/hashnode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashnode.js","sourceRoot":"","sources":["../../src/services/hashnode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,IAAI,QAA4B,CAAC;AAEjC,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,KAAa,EACb,SAAmC;IAEnC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,kDAAkD;YAChD,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAC/B,qBAAqB,EACrB,EAAE,KAAK,EAAE,SAAS,EAAE,EACpB;YACE,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,kBAAkB;gBAC1B,aAAa,EAAE,QAAQ;aACxB;YACD,OAAO,EAAE,MAAM;SAChB,CACF,CAAC;QAEF,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM;iBAC9B,GAAG,CAAC,CAAC,CAAsB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;iBAC1C,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAS,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,cAAc,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,QAAQ,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC9B,KAAK,GAAG;oBACN,OAAO,IAAI,KAAK,CACd,4CAA4C;wBAC1C,yDAAyD,CAC5D,CAAC;gBACJ,KAAK,GAAG;oBACN,OAAO,IAAI,KAAK,CACd,kEAAkE,CACnE,CAAC;gBACJ,KAAK,GAAG;oBACN,OAAO,IAAI,KAAK,CACd,wEAAwE,CACzE,CAAC;gBACJ;oBACE,OAAO,IAAI,KAAK,CACd,qCAAqC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAC7D,CAAC;YACN,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAClC,OAAO,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,IAAI,KAAK,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC"}

package/dist/tools/drafts.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDraftTools(server: McpServer): void;
+//# sourceMappingURL=drafts.d.ts.map

package/dist/tools/drafts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drafts.d.ts","sourceRoot":"","sources":["../../src/tools/drafts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA+HpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAkZ1D"}