@dalcontak/blogger-mcp-server 1.0.0 → 1.0.2

package/.github/workflows/publish.yml

@@ -6,6 +6,7 @@ on:
       - 'release/**'
 
 permissions:
+  contents: read
   id-token: write
 
 jobs:
@@ -32,3 +33,5 @@ jobs:
 
       - name: Publish to npm
         run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENTS.md

@@ -6,7 +6,7 @@ MCP (Model Context Protocol) server for Google's Blogger API. Allows AI models t
 interact with Blogger blogs via stdio or HTTP transport. Includes an optional web dashboard
 (Express + Socket.IO) on a separate port when `UI_PORT` is set. Written in TypeScript, targeting Node.js 20.
 
-Package: `@mcproadev/blogger-mcp-server` (v1.0.4)
+Package: `@dalcontak/blogger-mcp-server` (v1.0.4)
 
 ## Build / Run / Test Commands
 
@@ -47,6 +47,7 @@ src/
   config.ts           # Environment-based configuration object
   types.ts            # Shared interfaces and type definitions
   ui-manager.ts       # Express + Socket.IO web dashboard
+  *.test.ts           # Unit tests (Jest) alongside source files
 public/               # Static web UI assets (HTML/JS/CSS)
 dist/                 # Compiled output (committed to repo)
 ```
@@ -146,7 +147,6 @@ dist/                 # Compiled output (committed to repo)
 ## Known Issues / Gotchas
 
 - `dist/` directory is committed to the repo -- rebuild before committing if you change source
-- README.md has an unresolved merge conflict marker at line 171
 - HTTP mode in `index.ts` has a manual tool-routing switch that duplicates `server.ts` logic
 
 ## Deployment

package/README.md

@@ -1,169 +1,270 @@
-# blogger-mcp-server
-=======
-# Serveur MCP pour Blogger
+# Blogger MCP Server
 
-Un serveur MCP (Model Context Protocol) qui permet aux modèles d'intelligence artificielle comme Claude d'interagir directement avec l'API Blogger de Google.
+MCP (Model Context Protocol) server for Google's Blogger API. Allows AI models like Claude to interact with Blogger blogs.
 
-## À propos
+## Features
 
-Ce projet implémente un serveur compatible avec le protocole MCP (Model Context Protocol) pour l'API Blogger de Google. Il permet aux modèles d'IA comme Claude d'interagir avec les blogs Blogger pour :
+- **List and retrieve blogs** — Get blog details by ID or URL
+- **Posts management** — List, search, retrieve, create, update, delete posts
+- **Labels management** — List and retrieve labels
+- **Dual authentication**:
+  - **API Key** (read-only) — Access public blogs
+  - **OAuth2** (full access) — Create, update, delete posts, list your blogs
+- **Native search** — Uses Blogger's `posts/search` endpoint (not client-side filtering)
+- **Blog discovery** — `get_blog_by_url` tool to find blog ID from URL
+- **Optional Web UI** — Express + Socket.IO dashboard (enable with `UI_PORT`)
 
-* Lister et récupérer des blogs
-* Lister, rechercher, récupérer, créer, mettre à jour et supprimer des posts
-* Lister et récupérer des labels
-
-> **Note importante** : L'API Blogger de Google ne permet pas de créer de nouveaux blogs via API. Cette limitation est documentée par Google. Les blogs doivent être créés manuellement via l'interface web de Blogger.
-
-## Prérequis
-
-* Node.js (version 16 ou supérieure)
-* Une clé API Blogger de Google
+> **Note:** The Blogger API does not allow creating new blogs. Blogs must be created manually via the Blogger web interface.
 
 ## Installation
 
-### Installation depuis npm
+### From npm
 
 ```bash
-npm install -g @mcproadev/blogger-mcp-server
+npm install -g @dalcontak/blogger-mcp-server
 ```
 
-### Installation depuis le code source
+### From source
 
 ```bash
-git clone https://github.com/niyonabil/blogger-mcp-server.git
+git clone https://github.com/dalcontak/blogger-mcp-server.git
 cd blogger-mcp-server
 npm install
 npm run build
 ```
-if error install : 
 
-```bash
-npm install --save-dev @types/express
+## Authentication
+
+### Option 1: API Key (Read-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, 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`
+
+### Option 2: OAuth2 (Full Access)
+
+Required to create, update, delete posts, and list your own blogs. 
+
+**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).*
+
+**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`
+
+**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**.
+
+**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"
+}
 ```
-## Configuration
 
-### Obtenir une clé API Blogger
+> **Note:** If both API Key and OAuth2 are configured, OAuth2 is used.
+
+## Usage
+
+### Local Development
+
+```bash
+# Using npm package
+npm start
+
+# Or from source (after build)
+node dist/index.js
 
-1. Accédez à la [Console Google Cloud](https://console.cloud.google.com/)
-2. Créez un nouveau projet ou sélectionnez un projet existant
-3. Activez l'API Blogger v3
-4. Créez une clé API
-5. Notez cette clé pour l'utiliser dans la configuration
+# Development mode with ts-node
+npm run dev
+```
 
-### Configuration du serveur MCP
+### With MCP Client (Claude Desktop)
 
-Créez un fichier de configuration pour votre client MCP. Voici un exemple pour Claude Desktop :
+Create or edit your Claude Desktop config file:
+
+**Linux:** `~/.config/Claude/claude_desktop_config.json`  
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "blogger": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@mcproadev/blogger-mcp-server"
-      ],
+      "command": "node",
+      "args": ["./dist/index.js"],
       "env": {
-        "BLOGGER_API_KEY": "VOTRE_CLE_API_ICI"
+        "BLOGGER_API_KEY": "your_api_key_here"
       }
     }
   }
 }
 ```
 
-Remplacez `VOTRE_CLE_API_ICI` par la clé API que vous avez obtenue.
+Replace `/home/dalcon/dev/ai/blogger-mcp-server/dist/index.js` with your actual path, and set your API key or OAuth2 credentials.
+
+### Example Commands
 
-## Utilisation
+```json
+// List all your blogs (requires OAuth2)
+{"tool": "list_blogs", "params": {}}
 
-### Démarrage local
+// Get blog details by ID
+{"tool": "get_blog", "params": {"blogId": "123456789"}}
 
-Le projet inclut deux scripts pour faciliter le démarrage du serveur :
+// Find blog ID from URL (useful when you don't know the ID)
+{"tool": "get_blog_by_url", "params": {"url": "https://yourblog.blogspot.com"}}
 
-#### Mode développement
+// List posts
+{"tool": "list_posts", "params": {"blogId": "123456789", "maxResults": 10}}
 
-```bash
-export BLOGGER_API_KEY=votre_cle_api
-./start-dev.sh
-```
+// Search posts
+{"tool": "search_posts", "params": {"blogId": "123456789", "query": "technology"}}
 
-Ce script vérifie la présence de la clé API, installe les dépendances si nécessaire, compile le projet si nécessaire, puis démarre le serveur en mode développement.
+// Create a new post (requires OAuth2)
+{"tool": "create_post", "params": {"blogId": "123456789", "title": "My Post", "content": "Content here", "labels": ["tech", "nodejs"]}}
 
-#### Mode production
+// Update a post (requires OAuth2)
+{"tool": "update_post", "params": {"blogId": "123456789", "postId": "789012", "title": "Updated Title"}}
 
-```bash
-export BLOGGER_API_KEY=votre_cle_api
-npm run build
-./start-prod.sh
+// Delete a post (requires OAuth2)
+{"tool": "delete_post", "params": {"blogId": "123456789", "postId": "789012"}}
+
+// List labels
+{"tool": "list_labels", "params": {"blogId": "123456789"}}
+
+// Get label details
+{"tool": "get_label", "params": {"blogId": "123456789", "labelName": "technology"}}
 ```
 
-Ce script vérifie la présence de la clé API et que le projet est compilé, puis démarre le serveur en mode production.
+## Available Tools
+
+| Tool | Description | Auth Required |
+|-------|-------------|---------------|
+| `list_blogs` | Lists all your blogs | OAuth2 |
+| `get_blog` | Retrieves blog details by ID | None |
+| `get_blog_by_url` | Finds blog ID from URL | None |
+| `list_posts` | Lists posts from a blog | None |
+| `search_posts` | Searches posts (uses native API) | None |
+| `get_post` | Retrieves post details | None |
+| `create_post` | Creates a new post | OAuth2 |
+| `update_post` | Updates an existing post | OAuth2 |
+| `delete_post` | Deletes a post | OAuth2 |
+| `list_labels` | Lists all labels from a blog | None |
+| `get_label` | Retrieves label details | None |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BLOGGER_API_KEY` | (optional) | Google Blogger API key (read-only) |
+| `GOOGLE_CLIENT_ID` | (optional) | OAuth2 client ID (for full access) |
+| `GOOGLE_CLIENT_SECRET` | (optional) | OAuth2 client secret |
+| `GOOGLE_REFRESH_TOKEN` | (optional) | OAuth2 refresh token |
+| `MCP_MODE` | `stdio` | Transport: `stdio` or `http` |
+| `MCP_HTTP_HOST` | `0.0.0.0` | HTTP host (HTTP mode) |
+| `MCP_HTTP_PORT` | `3000` | HTTP port (HTTP mode) |
+| `BLOGGER_MAX_RESULTS` | `10` | Max results per query |
+| `BLOGGER_API_TIMEOUT` | `30000` | API timeout (ms) |
+| `LOG_LEVEL` | `info` | Logging level |
+| `UI_PORT` | (disabled) | Web UI port (set to enable) |
+
+**At least one auth method is required** — Either API key OR OAuth2 credentials.
+
+## Project Structure
 
-### Utilisation avec un client MCP
+```
+src/
+  index.ts            # Entry point, main() function, HTTP mode routing
+  server.ts           # MCP server tool registration (initMCPServer)
+  bloggerService.ts   # Google Blogger API wrapper (BloggerService class)
+  config.ts           # Environment-based configuration object
+  types.ts            # Shared interfaces and type definitions
+  ui-manager.ts       # Express + Socket.IO web dashboard
+  *.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
+```
 
-Une fois configuré, vous pouvez utiliser le serveur MCP pour Blogger avec n'importe quel client MCP compatible, comme Claude Desktop.
+## Development
 
-Exemples de commandes :
+```bash
+# Install dependencies
+npm install
 
-* "Liste tous mes blogs Blogger"
-* "Crée un nouveau post sur mon blog avec l'ID 123456 avec le titre 'Mon nouveau post' et le contenu 'Voici le contenu de mon post'"
-* "Recherche des posts contenant le mot 'technologie' dans mon blog"
-* "Mets à jour le post avec l'ID 789012 pour changer son titre en 'Nouveau titre'"
+# Run development (stdio mode, auto-compiles with ts-node)
+npm run dev
 
-## Options de déploiement
+# Run in HTTP mode (useful for manual testing with curl)
+MCP_MODE=http BLOGGER_API_KEY=your_key npm run dev
 
-### Déploiement sur Vercel
+# Run tests
+npm test
 
-Le projet inclut un fichier `vercel.json` pour faciliter le déploiement sur Vercel :
+# Build for production
+npm run build
+```
 
-1. Créez un compte sur [Vercel](https://vercel.com/) si vous n'en avez pas déjà un
-2. Installez l'outil CLI Vercel : `npm install -g vercel`
-3. Connectez-vous à votre compte Vercel : `vercel login`
-4. Configurez votre variable d'environnement secrète : `vercel secrets add blogger_api_key "VOTRE_CLE_API_ICI"`
-5. Déployez le projet : `vercel`
+## Deployment
 
-### Déploiement avec Docker
+### Vercel
 
-Le projet inclut un Dockerfile pour faciliter le déploiement dans un conteneur Docker :
+The project includes `vercel.json` for Vercel deployment:
 
-1. Construisez l'image Docker :
-   ```bash
-   docker build -t blogger-mcp-server .
-   ```
+1. Install Vercel CLI: `npm install -g vercel`
+2. Login: `vercel login`
+3. Deploy: `vercel`
 
-2. Exécutez le conteneur :
-   ```bash
-   docker run -p 3000:3000 -e BLOGGER_API_KEY=votre_cle_api blogger-mcp-server
-   ```
+### Docker
 
-### Autres options de déploiement
+Build and run:
 
-Le serveur peut également être déployé sur d'autres plateformes compatibles avec Node.js :
+```bash
+docker build -t blogger-mcp-server .
+docker run -p 3000:3000 -e BLOGGER_API_KEY=your_key blogger-mcp-server
+```
 
-1. **Heroku** : Utilisez un Procfile et les variables d'environnement Heroku
-2. **AWS Lambda** : Utilisez un adaptateur comme Serverless Framework
-3. **Google Cloud Run** : Utilisez le Dockerfile inclus
+### Other Platforms
 
-## Structure du projet
+The server can be deployed to any Node.js-compatible platform (Heroku, AWS Lambda, Google Cloud Run, etc.).
 
-Le serveur MCP pour Blogger est composé de plusieurs modules :
+## Release Process
 
-* `index.ts` : Point d'entrée principal
-* `server.ts` : Configuration du serveur MCP
-* `bloggerService.ts` : Service d'interaction avec l'API Blogger
-* `config.ts` : Configuration du serveur
-* `types.ts` : Définition des types et interfaces
+For publishing new versions to npm, see [RELEASE.md](./RELEASE.md).
 
-## Limitations connues
+## Contributing
 
-* **Création de blogs** : L'API Blogger de Google ne permet pas de créer de nouveaux blogs via API. Les blogs doivent être créés manuellement via l'interface web de Blogger.
-* **Recherche de posts** : La recherche utilise l'endpoint natif `posts/search?q=` de l'API Blogger v3.
-* **Gestion des labels** : L'API Blogger ne fournit pas d'endpoints directs pour la gestion des labels. Cette fonctionnalité est implémentée en extrayant les labels des posts.
-* **Authentification** : Le serveur supporte l'authentification par clé API (lecture seule, blogs publics) et OAuth2 (accès complet en lecture/écriture). OAuth2 est requis pour `list_blogs`, `create_post`, `update_post`, `delete_post`.
+Contributions are welcome! Feel free to open an issue or pull request.
 
-## Contribution
+## License
 
-Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.
+MIT
 
-## Licence
+## Acknowledgments
 
-Ce projet est sous licence MIT.
+- Built with [TypeScript](https://www.typescriptlang.org/)
+- Uses [googleapis](https://github.com/googleapis/google-api-nodejs-client) for Google APIs
+- MCP SDK by [Model Context Protocol](https://modelcontextprotocol.io/)

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 |