@atercates/bitbucket-mcp 1.0.0 → 1.0.1

package/docs/TRUSTED_PUBLISHING_SETUP.md

@@ -0,0 +1,169 @@
+# Guía de Setup: Trusted Publishing con NPM + GitHub Actions
+
+## Qué es Trusted Publishing
+
+Trusted Publishing permite publicar paquetes en npm **sin tokens secretos** (NPM_TOKEN). Usa OIDC (OpenID Connect) para que GitHub Actions se autentique directamente con npm, eliminando el riesgo de tokens expuestos o robados.
+
+---
+
+## Paso 1: Configurar Trusted Publishing en npmjs.com
+
+1. Inicia sesión en [npmjs.com](https://www.npmjs.com)
+2. Ve a tu paquete: `@atercates/bitbucket-mcp`
+3. Haz clic en **Settings** (pestaña)
+4. Busca la sección **Publishing access** → **Trusted Publisher**
+5. Rellena los campos **exactamente** así:
+
+| Campo | Valor |
+|-------|-------|
+| **Repository owner** | `atercates` |
+| **Repository name** | `bitbucket-mcp` |
+| **Workflow filename** | `auto-publish.yml` |
+| **Environment** | *(dejar vacío)* |
+
+6. Haz clic en **Add** o **Save**
+
+> **IMPORTANTE**: Los valores deben coincidir exactamente con tu repositorio y nombre del archivo del workflow. Si alguno no coincide, la autenticación OIDC fallará.
+
+---
+
+## Paso 2: Limpiar secretos obsoletos (si los hay)
+
+Si tenías un `NPM_TOKEN` configurado como secreto en GitHub:
+
+1. Ve a tu repo en GitHub → **Settings** → **Secrets and variables** → **Actions**
+2. **Elimina** el secreto `NPM_TOKEN` (interfiere con OIDC)
+
+> Con Trusted Publishing ya no necesitas ningún token de npm. El workflow se autentica automáticamente vía OIDC.
+
+---
+
+## Paso 3: Verificar el workflow
+
+El archivo `.github/workflows/auto-publish.yml` necesita estos elementos clave:
+
+### Permisos requeridos
+
+```yaml
+permissions:
+  contents: write    # Para crear tags y releases
+  id-token: write    # Para generar tokens OIDC (CRÍTICO)
+```
+
+### setup-node con registry-url
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    registry-url: 'https://registry.npmjs.org'  # Obligatorio para OIDC
+```
+
+### npm actualizado (>= 11.5.1)
+
+```yaml
+- name: Upgrade npm for OIDC support
+  run: npm install -g npm@latest
+```
+
+### Comando de publicación
+
+```yaml
+- name: Publish to npm
+  run: pnpm publish --provenance --access public --no-git-checks
+```
+
+Flags importantes:
+- `--provenance`: Genera atestación de procedencia (vincula el paquete al commit exacto)
+- `--access public`: Necesario para paquetes con scope (`@atercates/...`)
+- `--no-git-checks`: Evita que pnpm valide el estado git (ya lo controlamos nosotros)
+
+> **NO** uses `NODE_AUTH_TOKEN` ni `NPM_TOKEN` como variable de entorno en el paso de publicación. OIDC maneja la autenticación automáticamente.
+
+---
+
+## Paso 4: Verificar que funciona
+
+1. Haz un cambio en `src/` y push a `master`
+2. Ve a **Actions** en tu repo de GitHub
+3. El workflow "Build, Test & Auto-Publish" debería ejecutarse
+4. Verifica que el paso "Publish to npm" muestre algo como:
+
+```
+npm notice Publishing to https://registry.npmjs.org/ with tag latest and provenance
+```
+
+5. En npmjs.com, tu paquete debería mostrar un badge de **Provenance** verde
+
+---
+
+## Flujo del Pipeline
+
+```
+Push a master (cambios en src/)
+  │
+  ├── Job: build-and-test
+  │     ├── Install dependencies
+  │     ├── Lint
+  │     ├── Test
+  │     └── Build
+  │
+  └── Job: publish (necesita build-and-test exitoso)
+        ├── Checkout con historial completo
+        ├── Setup Node + registry npm
+        ├── Detectar si hay cambios desde último tag
+        ├── Bump versión patch en package.json
+        ├── Publicar con OIDC + provenance
+        ├── Push commit de versión + tag
+        └── Crear GitHub Release
+```
+
+---
+
+## Errores comunes y soluciones
+
+### `npm error code ENEEDAUTH`
+- **Causa**: Falta `registry-url` en setup-node, o npm < 11.5.1
+- **Solución**: Verifica que `registry-url: 'https://registry.npmjs.org'` está configurado y que ejecutas `npm install -g npm@latest`
+
+### `Trusted publishing configuration mismatch`
+- **Causa**: Los datos en npmjs.com no coinciden con el workflow
+- **Solución**: Verifica que owner, repo, workflow filename y environment coincidan exactamente
+
+### `npm error code E403 - Forbidden`
+- **Causa**: Token NPM_TOKEN interfiriendo con OIDC, o el paquete no tiene Trusted Publisher configurado
+- **Solución**: Elimina NPM_TOKEN de secrets y verifica la configuración en npmjs.com
+
+### `npm warn publish Skipping provenance`
+- **Causa**: El runner no es GitHub-hosted, o falta `id-token: write`
+- **Solución**: Verifica los permisos del workflow y que usas `ubuntu-latest`
+
+### El workflow se ejecuta pero no publica
+- **Causa**: No hay cambios en `src/` desde el último tag
+- **Solución**: El workflow solo publica cuando detecta cambios en código fuente. Es el comportamiento esperado.
+
+---
+
+## Publicación manual (local)
+
+Si necesitas publicar manualmente desde tu máquina:
+
+```bash
+# Necesitas estar autenticado en npm: npm login
+pnpm version patch
+pnpm publish --access public
+git push && git push --tags
+```
+
+> Nota: La publicación local NO genera provenance. Solo GitHub Actions con OIDC lo hace.
+
+---
+
+## Checklist final
+
+- [ ] Trusted Publisher configurado en npmjs.com con los datos exactos del repo
+- [ ] No hay `NPM_TOKEN` en los secrets de GitHub Actions
+- [ ] El workflow tiene `id-token: write` en permissions
+- [ ] `setup-node` tiene `registry-url: 'https://registry.npmjs.org'`
+- [ ] El comando publish usa `--provenance --access public`
+- [ ] npm se actualiza a >= 11.5.1 en el workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atercates/bitbucket-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Model Context Protocol (MCP) server for Bitbucket Cloud and Server API integration",
   "mcpName": "io.github.bitbucket-mcp/bitbucket-mcp",
   "type": "module",
@@ -28,11 +28,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/atercates/bitbucket-mcp"
+    "url": "git+https://github.com/ATERCATES/bitbucket-mcp"
   },
-  "homepage": "https://github.com/atercates/bitbucket-mcp#readme",
+  "homepage": "https://github.com/ATERCATES/bitbucket-mcp#readme",
   "bugs": {
-    "url": "https://github.com/atercates/bitbucket-mcp/issues"
+    "url": "https://github.com/ATERCATES/bitbucket-mcp/issues"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",

package/docs/guides/ENVIRONMENT_VARIABLES.md

@@ -1,306 +0,0 @@
-# Environment Variables Reference
-
-Complete list of environment variables needed to configure and deploy the Bitbucket MCP server.
-
-## Authentication (Required - Select One)
-
-### Token Authentication (Recommended)
-
-```bash
-# App password from Bitbucket
-BITBUCKET_TOKEN=your_app_password_here
-```
-
-**How to get:**
-1. Go to https://bitbucket.org/account/settings/app-passwords/
-2. Click "Create app password"
-3. Select permissions: Pipelines:Read, Repositories:Read+Write, Pull requests:Read+Write
-4. Copy the generated password
-
-### Basic Authentication
-
-```bash
-# Email and app password
-BITBUCKET_USERNAME=your_email@example.com
-BITBUCKET_PASSWORD=your_app_password_here
-```
-
-## Server Configuration (Optional)
-
-```bash
-# API base URL (defaults to Bitbucket Cloud)
-BITBUCKET_URL=https://api.bitbucket.org/2.0
-
-# For self-hosted Bitbucket Server:
-BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0
-
-# Default workspace (auto-extracted if not set)
-BITBUCKET_WORKSPACE=my-workspace
-
-# Allow dangerous operations (delete branch, delete tag, etc.)
-BITBUCKET_ALLOW_DANGEROUS=true  # default: false
-```
-
-## Logging Configuration (Optional)
-
-```bash
-# Disable file-based logging
-BITBUCKET_LOG_DISABLE=true
-
-# Custom log file path
-BITBUCKET_LOG_FILE=/var/log/bitbucket-mcp/server.log
-
-# Custom log directory
-BITBUCKET_LOG_DIR=/var/log/bitbucket-mcp
-
-# Create per-working-directory subdirectories
-BITBUCKET_LOG_PER_CWD=true
-```
-
-## NPM Publishing (Deployment)
-
-### Local Deployment
-
-```bash
-# npm account credentials
-# These are configured via: npm login
-# Stored in: ~/.npmrc (do NOT commit)
-```
-
-### CI/CD Deployment (GitHub Actions, etc.)
-
-```bash
-# npm access token for automation
-NPM_TOKEN=npm_your_token_here_1234567890
-
-# or use npm credentials
-NPM_USERNAME=your_npm_username
-NPM_PASSWORD=your_npm_password
-NPM_EMAIL=your_email@example.com
-```
-
-**How to get NPM_TOKEN:**
-1. Go to https://www.npmjs.com/settings/~/tokens
-2. Click "Generate New Token"
-3. Select type: "Automation" (for CI/CD)
-4. Copy the token
-5. Add to GitHub Secrets as `NPM_TOKEN`
-
-## Development Environment
-
-```bash
-# Development mode (use tsx watch)
-NODE_ENV=development
-pnpm dev
-
-# Production build
-NODE_ENV=production
-pnpm build
-pnpm start
-```
-
-## Complete Example: Local Setup
-
-```bash
-# Step 1: Create app password on Bitbucket
-# Go to https://bitbucket.org/account/settings/app-passwords/
-
-# Step 2: Set environment variables
-export BITBUCKET_TOKEN="your_app_password"
-export BITBUCKET_WORKSPACE="my-workspace"
-
-# Optional: Enable logging
-export BITBUCKET_LOG_DISABLE=false
-
-# Optional: Allow dangerous operations
-export BITBUCKET_ALLOW_DANGEROUS=true
-
-# Step 3: Run the server
-pnpm start
-# OR
-npx -y bitbucket-mcp@latest
-```
-
-## Complete Example: Docker Deployment
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY . .
-RUN pnpm install && pnpm build
-
-ENV BITBUCKET_TOKEN=${BITBUCKET_TOKEN}
-ENV BITBUCKET_WORKSPACE=${BITBUCKET_WORKSPACE}
-ENV BITBUCKET_LOG_DISABLE=false
-ENV BITBUCKET_ALLOW_DANGEROUS=${BITBUCKET_ALLOW_DANGEROUS:-false}
-
-CMD ["node", "dist/index.js"]
-```
-
-```bash
-# Run Docker container
-docker run -e BITBUCKET_TOKEN=your_token \
-           -e BITBUCKET_WORKSPACE=my-workspace \
-           bitbucket-mcp:latest
-```
-
-## Complete Example: GitHub Actions Workflow
-
-```yaml
-name: Deploy to npm
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 8
-      
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-          registry-url: 'https://registry.npmjs.org'
-          cache: 'pnpm'
-      
-      - run: pnpm install
-      - run: pnpm build
-      - run: pnpm test
-      - run: pnpm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-**GitHub Secrets to configure:**
-- `NPM_TOKEN`: npm automation token
-
-## Configuration by Environment
-
-### Development
-
-```bash
-BITBUCKET_TOKEN=dev_token
-BITBUCKET_WORKSPACE=dev-workspace
-BITBUCKET_LOG_DISABLE=false
-BITBUCKET_ALLOW_DANGEROUS=true
-NODE_ENV=development
-```
-
-### Staging
-
-```bash
-BITBUCKET_TOKEN=staging_token
-BITBUCKET_WORKSPACE=staging-workspace
-BITBUCKET_LOG_DISABLE=false
-BITBUCKET_ALLOW_DANGEROUS=false
-NODE_ENV=production
-```
-
-### Production
-
-```bash
-BITBUCKET_TOKEN=${BITBUCKET_TOKEN}
-BITBUCKET_WORKSPACE=${BITBUCKET_WORKSPACE}
-BITBUCKET_LOG_DISABLE=false
-BITBUCKET_ALLOW_DANGEROUS=false
-NODE_ENV=production
-```
-
-## Environment Variable Priority
-
-When multiple configuration sources exist, priority is:
-
-1. **Command-line environment variables** (highest)
-   ```bash
-   BITBUCKET_TOKEN=value pnpm start
-   ```
-
-2. **.env file in current directory**
-   ```bash
-   # .env
-   BITBUCKET_TOKEN=value
-   ```
-
-3. **.env.local file** (for local overrides)
-   ```bash
-   # .env.local (in .gitignore)
-   BITBUCKET_TOKEN=local_value
-   ```
-
-4. **System environment variables**
-   ```bash
-   export BITBUCKET_TOKEN=value
-   ```
-
-5. **Default values** (lowest, if any)
-
-## Security Best Practices
-
-1. **Never commit secrets**
-   - Add `.env` and `.env.local` to `.gitignore`
-   - Store tokens in environment or secret management
-
-2. **Use strong tokens**
-   - Use app passwords with minimal required scopes
-   - Rotate tokens regularly
-
-3. **Enable 2FA on npm account**
-   - https://docs.npmjs.com/about-two-factor-authentication
-
-4. **Use specific npm tokens for CI/CD**
-   - Create automation tokens instead of personal tokens
-   - Restrict token scope to "publish"
-
-5. **Disable dangerous operations in production**
-   - Only set `BITBUCKET_ALLOW_DANGEROUS=true` in development
-   - This prevents accidental data loss
-
-## Troubleshooting
-
-### "Invalid credentials" error
-
-```bash
-# Verify token is set
-echo $BITBUCKET_TOKEN
-
-# Test credentials
-curl -X GET https://api.bitbucket.org/2.0/user \
-  -H "Authorization: Bearer $BITBUCKET_TOKEN"
-```
-
-### "Workspace not found"
-
-```bash
-# Verify workspace name
-echo $BITBUCKET_WORKSPACE
-
-# List your workspaces
-curl -X GET https://api.bitbucket.org/2.0/workspaces \
-  -H "Authorization: Bearer $BITBUCKET_TOKEN"
-```
-
-### npm publish fails with "ENEEDAUTH"
-
-```bash
-# Check npm login
-npm whoami
-
-# Login again
-npm login
-
-# Or use token directly
-echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
-```
-
-## See Also
-
-- [Getting Started Guide](GETTING_STARTED.md)
-- [NPM Deployment Guide](NPM_DEPLOYMENT.md)
-- [Architecture Documentation](../architecture/ARCHITECTURE.md)