feat: initial release - Google AdSense MCP Server v0.1.0

- 11 MCP tools for AdSense data access
- OAuth and service account authentication
- SQLite caching with TTL-based invalidation
- Rate limiting with exponential backoff
- Read-only scope for safety
- CLI commands: init, doctor, run
- Multi-account support

Author: superzero11

.github/copilot-instructions.md

@@ -0,0 +1,77 @@
+# AdSense-MCP Copilot Instructions
+
+## Project Overview
+This is a **Model Context Protocol (MCP) server** that provides Google AdSense API access to AI clients (Claude, Cursor, VS Code Copilot). It's distributed as a CLI tool via npm (`adsense-mcp`) with OAuth/service account authentication.
+
+## Architecture
+
+```
+src/
+├── index.ts          # Public exports for programmatic use
+├── types.ts          # TypeScript types (single source of truth)
+├── cli/              # Commander-based CLI (`adsense-mcp init|doctor|run`)
+├── server/           # MCP server implementation
+│   ├── index.ts      # Server factory with stdio transport
+│   ├── tools/        # MCP tools organized by domain
+│   └── resources/    # MCP resources
+├── adsense/
+│   ├── client.ts     # AdSense API wrapper with all operations
+│   ├── rateLimiter.ts # Rate limiting with exponential backoff
+│   └── cache.ts      # SQLite cache with TTL
+└── auth/             # OAuth2 + service account auth, token storage
+```
+
+**Key data flows:**
+1. CLI commands → `createServer()` → MCP stdio transport
+2. Tool calls → `handleToolCall()` routes to domain handlers → `AdSenseClient` → Google API
+3. Tokens stored via `keytar` (OS keychain) with file fallback; config in `env-paths` directories
+
+## Development Commands
+
+```bash
+npm run build      # tsup build (ESM, Node 18+)
+npm run dev        # Watch mode
+npm run typecheck  # tsc --noEmit
+npm run lint       # eslint src/
+adsense-mcp doctor # Check auth and API access
+```
+
+## Code Conventions
+
+### Adding New MCP Tools
+1. Create tool definition in `src/server/tools/<domain>.ts` following the pattern:
+   - Export handler function like `handle<Action>(args)`
+2. Register in `src/server/tools/index.ts`:
+   - Add tool schema to `registerTools()` array
+   - Add case to `handleToolCall()` switch
+3. Tool names use underscore notation: `adsense_earnings_summary`, `adsense_list_sites`
+
+### Type Definitions
+- Define types in `src/types.ts`
+- Tool input schemas use plain JSON Schema format for MCP
+
+### Error Handling Pattern
+```typescript
+try {
+    const result = await client.someOperation();
+    return { data: result };
+} catch (error: any) {
+    return { error: error.message };
+}
+```
+
+### Rate Limiting
+- AdSense API: 100 requests/minute/user
+- Use `rateLimiter.throttle()` before API calls
+- Use `withRetry()` wrapper for automatic exponential backoff
+
+### Caching Strategy
+- Today's data: 5 minutes TTL (frequently changing)
+- Yesterday's data: 1 hour TTL
+- Historical data (>2 days): 24 hours TTL
+- Account/site info: 1 hour TTL
+
+## Security Notes
+- **Read-only scope only** (`adsense.readonly`) - no write operations
+- Never log or expose tokens
+- Credentials stored in OS keychain, never in repo

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run typecheck
+        run: npm run typecheck
+
+      - name: Run lint
+        run: npm run lint
+        continue-on-error: true
+
+      - name: Build
+        run: npm run build
+
+      - name: Test CLI
+        run: node dist/cli/index.js --help

.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Test
+coverage/
+.nyc_output/
+
+# Cache
+*.db
+*.sqlite
+
+# Credentials (never commit!)
+credentials.json
+service-account.json
+tokens.json

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-20
+
+### Added
+- Initial release
+- **Earnings**: Real-time earnings summary (today, yesterday, 7 days, month)
+- **Reports**: Custom reports with dimensions and metrics
+- **Period Comparison**: Compare performance between two time periods
+- **Sites**: List sites with approval status (READY, GETTING_READY, etc.)
+- **Alerts**: Account alerts and warnings by severity
+- **Policy Issues**: Policy violations affecting monetization
+- **Payments**: Payment history and pending earnings
+- **Ad Units**: List all ad units across ad clients
+- **Ad Code**: Get HTML embed code for ad units
+- **Export**: CSV export for reports
+- **Caching**: SQLite cache with TTL-based invalidation
+- **Rate Limiting**: Exponential backoff with 100 req/min limit
+- **Authentication**: OAuth2 and service account support
+- **Secure Storage**: Tokens stored in OS keychain via keytar
+
+### Tools (11 total)
+- `adsense_list_accounts` - List all AdSense accounts
+- `adsense_earnings_summary` - Quick earnings overview
+- `adsense_generate_report` - Custom performance reports
+- `adsense_compare_periods` - Compare two time periods
+- `adsense_list_sites` - Sites with approval status
+- `adsense_list_alerts` - Account alerts (INFO/WARNING/SEVERE)
+- `adsense_list_policy_issues` - Policy violations
+- `adsense_list_payments` - Payment history
+- `adsense_list_ad_units` - All ad units
+- `adsense_get_ad_code` - Get ad unit embed code
+- `adsense_export_csv` - Export report as CSV
+
+### Security
+- Read-only scope (`adsense.readonly`) by design for safety
+- No write operations to prevent accidental changes

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present SuperZero11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.