@dalcontak/blogger-mcp-server 1.0.1 → 1.0.3

package/.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
       - 'release/**'
 
 permissions:
-  contents: read
+  contents: write # Needed for creating GitHub Releases and Tags
   id-token: write
 
 jobs:
@@ -35,3 +35,32 @@ jobs:
         run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Extract version from package.json
+        id: package-version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="v${{ steps.package-version.outputs.version }}"
+          
+          # gh release create will automatically create the tag if it doesn't exist
+          # --generate-notes builds an automated changelog from commit history
+          gh release create "$VERSION" \
+            --title "Release $VERSION" \
+            --generate-notes \
+            --notes "### 📦 Installation
+          Available on npm: [npmjs.com/package/@dalcontak/blogger-mcp-server](https://www.npmjs.com/package/@dalcontak/blogger-mcp-server)
+          
+          You can run the server directly without installing it using \`npx\`:
+          \`\`\`bash
+          npx -y @dalcontak/blogger-mcp-server
+          \`\`\`
+          
+          Or install it globally:
+          \`\`\`bash
+          npm install -g @dalcontak/blogger-mcp-server
+          \`\`\`" \
+            --target $GITHUB_SHA

package/README.md

@@ -37,48 +37,54 @@ npm run build
 
 ### Option 1: API Key (Read-only)
 
-Access public blogs only.
+Access public blogs only. Useful if you only need to read data.
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Create/select a project or existing one
-3. Enable the **Blogger API v3**
-4. Create an **API Key**
-5. Set the environment variable:
+2. Create/select a project, then enable the **Blogger API v3**.
+3. Create an **API Key** under Credentials.
+4. Set the environment variable: `export BLOGGER_API_KEY=your_api_key_here`
 
-```bash
-export BLOGGER_API_KEY=your_api_key_here
-```
+### Option 2: OAuth2 (Full Access)
 
-Works for: `get_blog`, `get_blog_by_url`, `list_posts`, `get_post`, `search_posts`, `list_labels`, `get_label`
+Required to create, update, delete posts, and list your own blogs. 
 
-### Option 2: OAuth2 (Full Access)
+**Need a step-by-step visual guide?**  
+🔗 [**Read the complete tutorial on setting up OAuth2 for Blogger MCP here**](https://dalcontk.blogspot.com/2026/03/guia-paso-paso-como-configurar.html)  
+*(Note: This guide is written in Spanish. Feel free to use Google Translate if you need it in another language).*
 
-Required for: `list_blogs`, `create_post`, `update_post`, `delete_post`
+**Step 1: Configure OAuth Consent**
+1. In [Google Cloud Console](https://console.cloud.google.com/), go to **Google Auth Platform** > **Overview**.
+2. Under **Audience**, add your Google account as a Test User.
+3. Under **Data Access** (Scopes), add: `https://www.googleapis.com/auth/blogger`
 
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Navigate to **Credentials** > **Create Credentials**
-3. Select **OAuth client ID**
-4. Application type: **Web application** or **Desktop app**
-5. Name: Your app name
-6. Authorized redirect URI: `http://localhost` (or your actual redirect)
-7. Scopes: Select **`https://www.googleapis.com/auth/blogger`**
-8. Create credentials and note the **Client ID** and **Client Secret**
-
-To obtain a refresh token (one-time setup):
-- Use the [OAuth Playground](https://developers.google.com/oauthplayground/)
-- Select **Blogger API v3**
-- Choose `https://www.googleapis.com/auth/blogger` scope
-- Authorize and copy the **refresh token**
-
-Set environment variables:
+**Step 2: Create Web Credentials**
+1. Go to **Credentials** > **Create Credentials** > **OAuth client ID**.
+2. Application type: Select **Web application** *(do not use Desktop app)*.
+3. Name: Your app name.
+4. Authorized redirect URIs: Add exactly `https://developers.google.com/oauthplayground`
+5. Click Create and copy your **Client ID** and **Client Secret**.
 
-```bash
-export GOOGLE_CLIENT_ID=your_client_id
-export GOOGLE_CLIENT_SECRET=your_client_secret
-export GOOGLE_REFRESH_TOKEN=your_refresh_token
+**Step 3: Get a Refresh Token**
+1. Go to the [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).
+2. Click the **Gear icon** (top right) ⚙️ > check **Use your own OAuth credentials**.
+3. Paste your **Client ID** and **Client Secret**, then close the settings panel.
+4. In Step 1 (left panel), scroll to **Blogger API v3**, select `https://www.googleapis.com/auth/blogger`, and click **Authorize APIs**.
+5. Log in with your test Google account and grant permissions.
+6. In Step 2, click **Exchange authorization code for tokens**.
+7. Copy the generated **Refresh token**.
+
+**Step 4: Set Environment Variables**
+Configure your MCP client (like Claude Desktop or OpenCode) with:
+
+```json
+"env": {
+  "GOOGLE_CLIENT_ID": "your_client_id_here",
+  "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
+  "GOOGLE_REFRESH_TOKEN": "1//your_refresh_token_here"
+}
 ```
 
-> **Note:** If both authentication methods are configured, OAuth2 is used (it covers all operations).
+> **Note:** If both API Key and OAuth2 are configured, OAuth2 is used.
 
 ## Usage
 
@@ -108,7 +114,7 @@ Create or edit your Claude Desktop config file:
   "mcpServers": {
     "blogger": {
       "command": "node",
-      "args": ["/home/dalcon/dev/ai/blogger-mcp-server/dist/index.js"],
+      "args": ["./dist/index.js"],
       "env": {
         "BLOGGER_API_KEY": "your_api_key_here"
       }
@@ -197,7 +203,7 @@ src/
   config.ts           # Environment-based configuration object
   types.ts            # Shared interfaces and type definitions
   ui-manager.ts       # Express + Socket.IO web dashboard
-  tests/              # Unit tests (Jest)
+  *.test.ts           # Unit tests (Jest) alongside source files
   .github/workflows/ # GitHub Actions CI/CD
 public/               # Static web UI assets (HTML/JS/CSS)
 dist/                 # Compiled output

package/RELEASE.md

@@ -4,28 +4,55 @@ This document explains how to create releases and publish to npm.
 
 ## Prerequisites
 
-### Setup Trusted Publishing (OIDC)
+### Setup GitHub Actions Token + Trusted Publishing (Provenance)
 
-IMPORTANT: npm classic tokens are deprecated (revoked Nov 19, 2025). Fine-grained tokens have a 90-day maximum lifetime. The recommended approach is **Trusted Publishing (OIDC)**.
+We use a **hybrid approach** combining a classic automation token for authentication with OIDC (OpenID Connect) for cryptographic provenance signing.
 
-#### Step 1: Configure GitHub Actions as Trusted Publisher
+#### Step 1: Create Fine-grained Automation Token
+
+1. Log in to npm: `npm login`
+2. Generate an automation token (90-day lifetime):
+   ```bash
+   npm token create --name="github-actions" --scopes="dalcontak" --packages-and-scopes-permission="read-write" --bypass-2fa=true
+   ```
+3. Copy the token (starts with `npm_`)
+
+#### Step 2: Add Token to GitHub Secrets
+
+1. Go to your repository: https://github.com/dalcontak/blogger-mcp-server
+2. Navigate to **Settings** > **Secrets and variables** > **Actions**
+3. Click **"New repository secret"**
+4. Name: `NPM_TOKEN`
+5. Value: Paste the token from Step 1
+6. Click **"Add secret"**
+
+#### Step 3: Configure npm Package Settings for Automation Tokens
+
+1. Go to https://www.npmjs.com/package/@dalcontak/blogger-mcp-server
+2. Click on **"Settings"** tab
+3. In **Publishing access**, change to: **"Require two-factor authentication or a token"** (or similar option that allows automation tokens)
+4. Save the change
+
+⚠️ **Important:** If set to "Require 2FA" (without "or a token"), automation tokens will be rejected with error 403.
+
+#### Step 4: Configure GitHub Actions as Trusted Publisher (for Provenance)
+
+This enables cryptographic signing of published packages (npm provenance).
 
-The correct navigation is:
 1. Go to https://www.npmjs.com/package/@dalcontak/blogger-mcp-server
 2. Click on **"Settings"** tab
 3. Find the **"Trusted Publishers"** section
-4. Click on **"GitHub Actions"** (or "Set up connection" button)
+4. Click on **"Set up connection"**
 5. Fill in:
-   - **Organization or user**: `dalcontak`
-   - **Repository**: `dalcontak/blogger-mcp-server`
-   - **Workflow filename**: `publish.yml` (name of the workflow file, NOT the full path)
+    - **Organization or user**: `dalcontak`
+    - **Repository**: `dalcontak/blogger-mcp-server`
+    - **Workflow filename**: `publish.yml`
 6. Click **"Set up connection"**
 
-Optional but recommended:
-- ✅ **Require two-factor authentication**
-- ✅ **Disallow tokens** (forces OIDC usage)
-
-That's it! No token needed — OIDC generates short-lived, job-specific credentials automatically.
+That's it! The workflow will now:
+- Authenticate with your `NPM_TOKEN` secret
+- Sign packages with GitHub Actions provenance
+- Publish to npm securely
 
 ## Version Naming
 
@@ -76,7 +103,7 @@ GitHub Actions will automatically:
 3. ✅ Install dependencies
 4. ✅ Run tests (npm test)
 5. ✅ Build (npm run build)
-6. ✅ Publish to npm using OIDC (no manual token needed)
+6. ✅ Publish to npm using `NPM_TOKEN` + provenance signing
 
 The workflow triggers on any push to branches matching `release/**`.
 
@@ -97,29 +124,34 @@ npm install @dalcontak/blogger-mcp-server
 - The branch name **must** contain version after "release-" (e.g., `release-1.1.7`)
 - Version format: **3 digits separated by dots** (X.Y.Z)
 - Only pushes to `release/**` branches trigger the build/publish workflow
-- **No GitHub secrets needed** for OIDC — just configure trusted publisher connection
-- Requires Node.js >= 11.5.1 (npm automatically detects OIDC credentials)
+- **NPM_TOKEN secret is required** in GitHub Actions for authentication (automation token)
+- Token lifetime is 90 days maximum — remember to recreate and update secret before expiration
+- Requires Node.js >= 20 (used in workflow)
 
 ## Troubleshooting
 
-### Error: "You are not set up to publish with OIDC"
+### Error: "Two-factor authentication is required but an automation token was specified"
+
+**Solution:** Make sure npm package settings allow automation tokens:
+1. Go to https://www.npmjs.com/package/@dalcontak/blogger-mcp-server > Settings
+2. Change **Publishing access** to: "Require two-factor authentication or a token"
+3. Save and try the workflow again
+
+### Error: "E403: You cannot publish over previously published versions"
 
-Make sure:
-1. GitHub Actions is configured as **Trusted Publisher** in npm settings
-2. Workflow filename matches: `publish.yml`
-3. Repository is correct: `dalcontak/blogger-mcp-server`
-4. Workflow has `permissions: id-token: write`
+**Solution:** This is normal. You cannot republish an existing version. Bump the version in `package.json` and create a new release branch.
 
-### Error: "npm publish --provenance requires Node.js >= 11.5.1"
+### Error: "E404: Package not in this registry"
 
-The workflow uses `actions/setup-node@v6` which sets up Node.js 20. If you see this error, check your Node.js version.
+**Solution:** Make sure `NPM_TOKEN` is set as a GitHub secret and that the token has write permissions for `@dalcontak` scope.
 
-## Comparison: Tokens vs OIDC
+## Comparison: Token vs OIDC (Provenance)
 
-| Aspect | Classic Tokens | Fine-grained Tokens | Trusted Publishing (OIDC) |
-|---------|----------------|--------------------|---------------------------|
-| **Status** | ❌ Deprecated (revoked) | ⚠️ Limited to 90 days | ✅ Recommended |
-| **Rotation** | Manual (every 90 days max) | Manual (every 90 days max) | Automatic (job-specific) |
-| **Security** | Long-lived, stored in secrets | Short-lived, stored in secrets | Short-lived, job-specific |
-| **GitHub Secret** | Required (NPM_TOKEN) | Required (NPM_TOKEN) | ❌ Not needed |
-| **Setup** | Create token, add to secrets | Create token, add to secrets | Configure in npmjs.com |
+| Aspect | Fine-grained Token | OIDC (Provenance) | Our Hybrid Approach |
+|---------|--------------------|---------------------|-------------------|
+| **Purpose** | Authentication (publish permission) | Cryptographic signing (supply chain security) | Both combined |
+| **Status** | ⚠️ Limited to 90 days | ✅ Standard feature | ✅ Best practice |
+| **Rotation** | Manual (recreate every 90 days) | Automatic (job-specific) | Token manual, OIDC automatic |
+| **Security** | Stored in GitHub secrets | Job-specific, short-lived | Multi-layer security |
+| **GitHub Secret** | Required (NPM_TOKEN) | ❌ Not needed | Required (NPM_TOKEN) |
+| **Setup** | Create via CLI, add to secret | Configure in npmjs.com | Both steps required |

package/dist/bloggerService.d.ts

@@ -1,121 +1,28 @@
 import { blogger_v3 } from 'googleapis';
-import { BloggerBlog, BloggerPost, BloggerLabel } from './types';
-/**
- * Custom types to compensate for Blogger API limitations
- */
+import { BloggerPost } from './types';
 interface BloggerLabelList {
     kind?: string;
-    items?: BloggerLabel[];
+    items?: Array<{
+        name: string;
+    }>;
 }
-/**
- * Google Blogger API interaction service
- *
- * Supports two authentication modes:
- * - OAuth2 (GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + GOOGLE_REFRESH_TOKEN):
- *   full access (read + write). Required for listBlogs, createPost, updatePost, deletePost.
- * - API Key (BLOGGER_API_KEY): read-only access to public blogs.
- *   Works for getBlog, listPosts, getPost, searchPosts, listLabels, getLabel.
- *
- * If both are configured, OAuth2 is used (it covers all operations).
- */
 export declare class BloggerService {
     private blogger;
     private readonly isOAuth2;
-    /**
-     * Initializes the Blogger service with OAuth2 or API key
-     */
     constructor();
-    /**
-     * Checks that OAuth2 authentication is available.
-     * Throws an explicit error if the operation requires OAuth2 and we are in API key mode.
-     */
     private requireOAuth2;
-    /**
-     * Lists all blogs for the authenticated user.
-     * Requires OAuth2 (blogs.listByUser with userId: 'self').
-     * @returns Blog list
-     */
     listBlogs(): Promise<blogger_v3.Schema$BlogList>;
-    /**
-     * Retrieves details of a specific blog
-     * @param blogId ID of the blog to retrieve
-     * @returns Blog details
-     */
     getBlog(blogId: string): Promise<blogger_v3.Schema$Blog>;
-    /**
-     * Retrieves a blog by its URL
-     * @param url Blog URL
-     * @returns Blog details
-     */
     getBlogByUrl(url: string): Promise<blogger_v3.Schema$Blog>;
-    /**
-     * Simulates blog creation.
-     * Note: The Blogger API does not actually allow creating a blog via API.
-     * This method simulates the functionality and returns an explanatory error message.
-     *
-     * @param blogData Blog data to create
-     * @returns Explanatory error message
-     */
-    createBlog(blogData: Partial<BloggerBlog>): Promise<any>;
-    /**
-     * Lists posts from a blog
-     * @param blogId Blog ID
-     * @param maxResults Maximum number of results to return
-     * @returns Post list
-     */
     listPosts(blogId: string, maxResults?: number): Promise<blogger_v3.Schema$PostList>;
-    /**
-     * Searches posts in a blog using the native posts.search endpoint of the Blogger API
-     * @param blogId Blog ID
-     * @param query Search term
-     * @param maxResults Maximum number of results to return
-     * @returns List of matching posts
-     */
     searchPosts(blogId: string, query: string, maxResults?: number): Promise<blogger_v3.Schema$PostList>;
-    /**
-     * Retrieves a specific post
-     * @param blogId Blog ID
-     * @param postId Post ID
-     * @returns Post details
-     */
     getPost(blogId: string, postId: string): Promise<blogger_v3.Schema$Post>;
-    /**
-     * Creates a new post in a blog.
-     * Requires OAuth2.
-     * @param blogId Blog ID
-     * @param postData Post data to create
-     * @returns Created post
-     */
     createPost(blogId: string, postData: Partial<BloggerPost>): Promise<blogger_v3.Schema$Post>;
-    /**
-     * Updates an existing post.
-     * Requires OAuth2.
-     * @param blogId Blog ID
-     * @param postId Post ID
-     * @param postData Post data to update
-     * @returns Updated post
-     */
     updatePost(blogId: string, postId: string, postData: Partial<BloggerPost>): Promise<blogger_v3.Schema$Post>;
-    /**
-     * Deletes a post.
-     * Requires OAuth2.
-     * @param blogId Blog ID
-     * @param postId Post ID
-     * @returns Deletion status
-     */
     deletePost(blogId: string, postId: string): Promise<void>;
-    /**
-     * Lists labels from a blog
-     * @param blogId Blog ID
-     * @returns Label list
-     */
     listLabels(blogId: string): Promise<BloggerLabelList>;
-    /**
-     * Retrieves a specific label
-     * @param blogId Blog ID
-     * @param labelName Label name
-     * @returns Label details
-     */
-    getLabel(blogId: string, labelName: string): Promise<BloggerLabel>;
+    getLabel(blogId: string, labelName: string): Promise<{
+        name: string;
+    }>;
 }
 export {};