refactor: add API client

.env.test.example

@@ -0,0 +1,3 @@
+# Test environment configuration
+TEST_API_BASE_URL=http://localhost:8010
+TEST_API_TOKEN=your_posthog_api_token_here

.github/workflows/pr-checks.yml

@@ -14,8 +14,6 @@ jobs:
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

.gitignore

@@ -4,6 +4,7 @@ node_modules
 .wrangler
 .dev.vars*
 .mcp.json
+.env.test
 
 # Editor-specific files
 .cursor/

CLAUDE.md

@@ -17,10 +17,11 @@ This is a PostHog MCP (Model Context Protocol) server built on Cloudflare Worker
 ### Key Components
 
 - **Main MCP Class (`src/index.ts`)**: `MyMCP` extends `McpAgent` and defines all available tools for interacting with PostHog
-- **API Layer (`src/posthogApi.ts`)**: Functions for making requests to PostHog's REST API
+- **Unified API Client (`src/api/client.ts`)**: `ApiClient` class provides type-safe methods for all PostHog API interactions with proper error handling and schema validation
 - **Schema Validation (`src/schema/`)**: Zod schemas for validating API requests and responses
 - **Caching (`src/lib/utils/cache/`)**: User-scoped memory cache for storing project/org state
 - **Documentation Search (`src/inkeepApi.ts`)**: Integration with Inkeep for PostHog docs search
+- **Utility Functions (`src/lib/utils/api.ts`)**: Helper functions for pagination and URL generation
 
 ### Authentication & State Management
 
@@ -29,19 +30,38 @@ This is a PostHog MCP (Model Context Protocol) server built on Cloudflare Worker
 - Automatic project/org selection when user has only one option
 - State persists across requests within the same session
 
+### API Architecture
+
+The codebase uses a unified API client pattern:
+
+- **API Client (`ApiClient`)**: Central class that handles all PostHog API requests with consistent error handling, authentication, and response validation
+- **Resource Methods**: API client is organized into resource-based methods:
+  - `organizations()`: Organization CRUD and project listing
+  - `projects()`: Project details and property definitions
+  - `featureFlags()`: Feature flag CRUD operations
+  - `insights()`: Insight CRUD, listing, and SQL queries
+  - `dashboards()`: Dashboard CRUD and insight management
+  - `query()`: Generic query execution for analytics
+  - `users()`: User information and authentication
+- **Type Safety**: All methods return `Result<T, Error>` types with proper TypeScript definitions
+- **URL Generation**: Uses configurable `BASE_URL` from constants for environment-aware URLs (localhost in dev, PostHog production in prod)
+
 ### Tool Categories
 
 1. **Organization/Project Management**: Get orgs, projects, set active context
-2. **Feature Flags**: CRUD operations on feature flags
-3. **Error Tracking**: Query errors and error details
-4. **Data Warehouse**: SQL insights via natural language queries
-5. **Documentation**: Search PostHog docs via Inkeep API
-6. **Analytics**: LLM cost tracking and other metrics
+2. **Feature Flags**: CRUD operations on feature flags  
+3. **Insights & Dashboards**: CRUD operations on insights and dashboards with proper URL generation
+4. **Error Tracking**: Query errors and error details
+5. **Data Warehouse**: SQL insights via natural language queries
+6. **Documentation**: Search PostHog docs via Inkeep API
+7. **Analytics**: LLM cost tracking and other metrics
 
 ### Environment Setup
 
 - Create `.dev.vars` file with `INKEEP_API_KEY` for docs search functionality
 - API token passed via Authorization header from MCP client configuration
+- **Development Mode**: Set `DEV = true` in `src/lib/constants.ts` to use `http://localhost:8010` for API calls and URLs
+- **Production Mode**: Set `DEV = false` to use `https://us.posthog.com` for API calls and URLs
 
 ### Code Style
 

package.json

@@ -7,21 +7,27 @@
 		"dev": "wrangler dev",
 		"format": "biome format --write",
 		"lint:fix": "biome lint --fix",
+		"test": "vitest",
+		"test:watch": "vitest watch",
 		"start": "wrangler dev",
 		"cf-typegen": "wrangler types",
 		"prepare": "husky"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
-		"@types/node": "^22.15.18",
+		"@types/node": "^22.15.34",
+		"dotenv": "^16.4.7",
 		"husky": "^9.1.7",
 		"typescript": "^5.8.3",
+		"vitest": "^3.2.4",
 		"wrangler": "^4.14.4"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.11.1",
+		"@types/dotenv": "^6.1.1",
 		"agents": "^0.0.80",
 		"posthog-node": "^4.18.0",
 		"zod": "^3.24.4"
-	}
+	},
+	"packageManager": "pnpm@9.15.5+sha256.8472168c3e1fd0bff287e694b053fccbbf20579a3ff9526b6333beab8df65a8d"
 }