duoops 0.2.1 → 0.2.3

package/mcp-server/data/runtime-pue-mappings.json

@@ -0,0 +1,183 @@
+{
+  "metadata": {
+    "generatedAt": "2025-06-14T16:09:07.455Z",
+    "methodology": "Real-time Electricity Maps API with industry standard PUE",
+    "availableZones": [
+      "US-CENT-SWPP"
+    ]
+  },
+  "regions": {
+    "us-central1": {
+      "zone": "US-CENT-SWPP",
+      "industryStandardPUE": 1.1,
+      "realTimeCarbonIntensity": 492,
+      "googleOfficialIntensity": 430,
+      "cfe": 0.95
+    },
+    "us-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-east4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-south1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west6": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west8": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west9": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west10": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west12": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-north1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-central2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-southwest1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-east2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-south1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-south2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-southeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-southeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "australia-southeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "australia-southeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "southamerica-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "northamerica-northeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "northamerica-northeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    }
+  }
+}

package/mcp-server/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@duoops/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for DuoOps carbon metrics",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@google-cloud/bigquery": "^8.1.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.7.9",
+    "express": "^4.21.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/mcp-server/src/auth.ts

@@ -0,0 +1,73 @@
+/* eslint-disable camelcase */
+import axios from 'axios'
+import {NextFunction, Request, Response} from 'express'
+
+export const GITLAB_URL = process.env.GITLAB_URL || 'https://gitlab.com'
+
+export async function validateGitLabToken(token: string): Promise<boolean> {
+  try {
+    const response = await axios.get(`${GITLAB_URL}/api/v4/user`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    })
+    return response.status === 200
+  } catch (error) {
+    console.error('GitLab token validation failed:', error)
+    return false
+  }
+}
+
+export function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  // Skip auth for well-known discovery endpoints
+  if (req.path.startsWith('/.well-known/')) {
+    return next()
+  }
+
+  // Check for Authorization header
+  const authHeader = req.headers.authorization
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return sendUnauthorized(res)
+  }
+
+  const token = authHeader.split(' ')[1]
+  
+  validateGitLabToken(token)
+    .then((isValid) => {
+      if (isValid) {
+        next()
+      } else {
+        sendUnauthorized(res)
+      }
+    })
+    .catch(() => sendUnauthorized(res))
+}
+
+function sendUnauthorized(res: Response) {
+  // Return 401 with WWW-Authenticate header pointing to GitLab discovery
+  // The resource_id is the URL of THIS server (the MCP server)
+  const resourceId = process.env.MCP_SERVER_URL || `https://${process.env.RAILWAY_STATIC_URL || 'localhost'}`
+  
+  // Per RFC 9728, we point to our own protected resource metadata endpoint
+  // which then points to the authorization server (GitLab)
+  res.setHeader('WWW-Authenticate', `OAuth p="ignored", resource_metadata="${resourceId}/.well-known/oauth-protected-resource"`)
+  res.status(401).send('Unauthorized')
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function oauthEndpoints(app: any) {
+  app.get('/.well-known/oauth-protected-resource', (req: Request, res: Response) => {
+    res.json({
+      authorization_servers: [
+        GITLAB_URL
+      ],
+      resource: process.env.MCP_SERVER_URL || `https://${req.get('host')}`,
+      scopes_supported: ["api", "read_user"]
+    })
+  })
+
+  // If GitLab doesn't strictly follow RFC 8414 at /.well-known/oauth-authorization-server,
+  // we might need to proxy or hardcode its endpoints here.
+  // But GitLab does support OIDC discovery at /.well-known/openid-configuration
+  // For MCP, the client should resolve the auth server metadata from the URL we provided above.
+}

package/mcp-server/src/index.ts

@@ -0,0 +1,58 @@
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
+import {SSEServerTransport} from '@modelcontextprotocol/sdk/server/sse.js'
+import express from 'express'
+
+import {authMiddleware, oauthEndpoints} from './auth.js'
+import {registerEmissionsTools} from './tools/emissions.js'
+import {registerProfileTools} from './tools/profiles.js'
+
+async function main() {
+  const server = new McpServer({
+    name: 'duoops-carbon',
+    version: '1.0.0',
+  })
+
+  // Register tools
+  registerEmissionsTools(server)
+  registerProfileTools(server)
+
+  const app = express()
+
+  app.get('/health', (_req, res) => {
+    res.json({service: 'duoops-mcp', status: 'ok', version: '1.0.0'})
+  })
+
+  oauthEndpoints(app)
+
+  // MCP SSE Transport setup
+  let transport: SSEServerTransport
+
+  app.get('/sse', authMiddleware, async (req, res) => {
+    transport = new SSEServerTransport('/message', res)
+    await server.connect(transport)
+  })
+
+  app.post('/message', authMiddleware, async (req, res) => {
+    if (!transport) {
+      res.sendStatus(400)
+      return
+    }
+
+    await transport.handlePostMessage(req, res)
+  })
+
+  // Legacy/Simple HTTP endpoint (optional, if SSE not supported by some clients)
+  // Currently we focus on SSE as per SDK standard for HTTP transport
+
+  const port = process.env.PORT || 8080
+  app.listen(port, () => {
+    console.log(`DuoOps MCP Server running on port ${port}`)
+    console.log(`OAuth discovery at /.well-known/oauth-protected-resource`)
+  })
+}
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+main().catch((error) => {
+  console.error('Fatal error:', error)
+  process.exit(1) // eslint-disable-line n/no-process-exit, unicorn/no-process-exit
+})

package/mcp-server/src/lib/bigquery.ts

@@ -0,0 +1,122 @@
+/* eslint-disable camelcase */
+import {BigQuery} from '@google-cloud/bigquery'
+
+import {EmissionsRecord} from './types.js'
+
+export class BigQueryService {
+  private bigquery: BigQuery
+  private datasetId: string
+  private projectId: string
+  private tableId: string
+
+  constructor() {
+    this.projectId = process.env.GCP_PROJECT_ID || ''
+    this.datasetId = process.env.BQ_DATASET || ''
+    this.tableId = process.env.BQ_TABLE || ''
+
+    if (!this.projectId || !this.datasetId || !this.tableId) {
+      console.warn('BigQuery configuration missing: GCP_PROJECT_ID, BQ_DATASET, or BQ_TABLE env vars not set.')
+    }
+
+    this.bigquery = new BigQuery({projectId: this.projectId})
+  }
+
+  async getJobEmissions(jobId: number, projectId?: number): Promise<EmissionsRecord | null> {
+    const query = `
+      SELECT
+        job_id,
+        pipeline_id,
+        gitlab_project_id as project_id,
+        machine_type,
+        region,
+        total_emissions,
+        (cpu_energy_kwh + ram_energy_kwh) as total_energy_kwh,
+        created_at,
+        runtime_seconds
+      FROM \`${this.projectId}.${this.datasetId}.${this.tableId}\`
+      WHERE job_id = @jobId
+      ${projectId ? 'AND gitlab_project_id = @projectId' : ''}
+      LIMIT 1
+    `
+
+    const options = {
+      params: {jobId, projectId},
+      query,
+    }
+
+    const [rows] = await this.bigquery.query(options)
+    return rows.length > 0 ? (rows[0] as EmissionsRecord) : null
+  }
+
+  async getPipelineEmissions(pipelineId: number, projectId?: number): Promise<{
+    jobs: Partial<EmissionsRecord>[];
+    pipeline_id: number;
+    total_emissions_g: number;
+    total_energy_kwh: number;
+  }> {
+    const query = `
+      SELECT
+        job_id,
+        machine_type,
+        total_emissions,
+        (cpu_energy_kwh + ram_energy_kwh) as total_energy_kwh,
+        runtime_seconds
+      FROM \`${this.projectId}.${this.datasetId}.${this.tableId}\`
+      WHERE pipeline_id = @pipelineId
+      ${projectId ? 'AND gitlab_project_id = @projectId' : ''}
+    `
+
+    const options = {
+      params: {pipelineId, projectId},
+      query,
+    }
+
+    const [rows] = await this.bigquery.query(options)
+    
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const totalEmissions = rows.reduce((sum: number, row: any) => sum + (row.total_emissions || 0), 0)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const totalEnergy = rows.reduce((sum: number, row: any) => sum + (row.total_energy_kwh || 0), 0)
+
+    return {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      jobs: rows.map((r: any) => ({
+        job_id: r.job_id,
+        machine_type: r.machine_type,
+        runtime_seconds: r.runtime_seconds,
+        total_emissions: r.total_emissions,
+        total_energy_kwh: r.total_energy_kwh
+      })),
+      pipeline_id: pipelineId,
+      total_emissions_g: totalEmissions,
+      total_energy_kwh: totalEnergy
+    }
+  }
+
+  async getProjectEmissionsSummary(projectId: number, limit: number = 10): Promise<EmissionsRecord[]> {
+    const query = `
+      SELECT
+        job_id,
+        pipeline_id,
+        gitlab_project_id as project_id,
+        machine_type,
+        region,
+        total_emissions,
+        (cpu_energy_kwh + ram_energy_kwh) as total_energy_kwh,
+        created_at,
+        runtime_seconds
+      FROM \`${this.projectId}.${this.datasetId}.${this.tableId}\`
+      WHERE gitlab_project_id = @projectId
+      ORDER BY created_at DESC
+      LIMIT @limit
+    `
+
+    const options = {
+      params: {limit, projectId},
+      query,
+    }
+
+    const [rows] = await this.bigquery.query(options)
+    return rows as EmissionsRecord[]
+  }
+}

package/mcp-server/src/lib/intensity.ts

@@ -0,0 +1,33 @@
+export class IntensityProvider {
+  async getCarbonIntensity(zone: string): Promise<number> {
+    // Electricity Maps API or similar would go here.
+    // For this implementation, we'll return a static average if we can't fetch real data,
+    // or simulate a fetch to public carbon intensity APIs if available without auth.
+    // This mirrors the CLI's simple implementation which currently uses static fallbacks or public APIs.
+    
+    // Simplification for the hackathon: use a mapping of common zones to average intensities
+    const averages: Record<string, number> = {
+      'AU': 300,
+      'BR': 600,
+      'DE': 350,
+      'FR': 50,
+      'GB': 60,
+      'IE': 230,
+      'IN': 650,
+      'JP': 600,
+      'NL': 350,
+      'US-CAL-CISO': 370,
+      'US-MIDA-PJM': 390,
+      'US-NW-PACW': 150,
+      'US-NY-NYIS': 300,
+      'US-TEX-NYIS': 400,
+    }
+
+    // Try to find a match or partial match
+    for (const [key, value] of Object.entries(averages)) {
+      if (zone.includes(key)) return value
+    }
+
+    return 475 // Global average fallback
+  }
+}

package/mcp-server/src/lib/power-profiles.ts

@@ -0,0 +1,102 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {CloudProvider, MachineProfile, PowerPoint} from './types.js'
+
+type RawMachineProfile = {
+  cpu_power_profile?: PowerPoint[];
+  matched_cpu_profile?: string;
+  memory_gb: number | string;
+  platform_cpu?: string;
+  ram_power_profile?: unknown;
+  scope3_emissions_hourly?: number;
+  vcpus: number | string;
+}
+
+type RawCpuProfile = {
+  power_profile: PowerPoint[];
+  tdp_watts: number;
+}
+
+type CpuPhysicalSpec = {
+  architecture: string;
+  cores: number;
+  note?: string;
+  source: string;
+  source_name: string;
+  tdp_watts: number;
+  threads: number;
+}
+
+type CpuPhysicalSpecs = Record<string, CpuPhysicalSpec> & {
+  _metadata: Record<string, string>;
+}
+
+export class PowerProfileRepository {
+  private awsMachines: null | Record<string, RawMachineProfile> = null
+  private cpuPhysicalSpecs: CpuPhysicalSpecs | null = null
+  private cpuProfiles: null | Record<string, RawCpuProfile> = null
+  private gcpMachines: null | Record<string, RawMachineProfile> = null
+  
+  // Default to ./data relative to CWD, which works in the container
+  constructor(private readonly dataDir: string = path.resolve(process.cwd(), 'data')) {}
+
+  async getMachineProfile(provider: CloudProvider, machineType: string): Promise<MachineProfile | null> {
+    const machines = this.loadMachineData(provider)
+    const raw = machines[machineType]
+    if (!raw) return null
+
+    const powerProfile = raw.cpu_power_profile ? this.normalizePowerPoints(raw.cpu_power_profile) : []
+
+    return {
+      cpuPowerProfile: powerProfile,
+      machineType,
+      matchedCpuProfile: raw.matched_cpu_profile,
+      memoryGb: this.normalizeNumber(raw.memory_gb),
+      platformCpu: raw.platform_cpu,
+      scope3EmissionsHourly: raw.scope3_emissions_hourly,
+      vcpus: this.normalizeNumber(raw.vcpus),
+    }
+  }
+
+  private loadJsonFile<T>(filename: string): T {
+    const filePath = path.join(this.dataDir, filename)
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8')
+      return JSON.parse(raw) as T
+    } catch (error) {
+      console.error(`Failed to load data file ${filename}:`, error)
+      return {} as T
+    }
+  }
+
+  private loadMachineData(provider: CloudProvider): Record<string, RawMachineProfile> {
+    if (provider === 'gcp') {
+      if (!this.gcpMachines) {
+        this.gcpMachines = this.loadJsonFile<Record<string, RawMachineProfile>>('gcp_machine_power_profiles.json')
+      }
+
+      return this.gcpMachines
+    }
+
+    if (!this.awsMachines) {
+      this.awsMachines = this.loadJsonFile<Record<string, RawMachineProfile>>('aws_machine_power_profiles.json')
+    }
+
+    return this.awsMachines
+  }
+
+  private normalizeNumber(value: number | string | undefined): number {
+    if (typeof value === 'number') return value
+    if (!value) return 0
+    const parsed = Number.parseFloat(value)
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+
+  private normalizePowerPoints(points: PowerPoint[]): PowerPoint[] {
+    return points.map((p) => ({
+      percentage: Number(p.percentage),
+      watts: Number(p.watts),
+    })).sort((a, b) => a.percentage - b.percentage)
+  }
+}

package/mcp-server/src/lib/types.ts

@@ -0,0 +1,66 @@
+// Copied and adapted from src/lib/measure/types.ts
+
+export type CloudProvider = 'aws' | 'gcp';
+
+export interface TimeseriesPoint {
+  timestamp: string;
+  value: number;
+}
+
+export interface JobInput {
+  cpuTimeseries: TimeseriesPoint[];
+  machineType: string;
+  provider: CloudProvider;
+  ramSizeTimeseries?: TimeseriesPoint[];
+  ramUsedTimeseries: TimeseriesPoint[];
+  region: string;
+}
+
+export interface PowerPoint {
+  percentage: number;
+  watts: number;
+}
+
+export interface MachineProfile {
+  cpuPowerProfile?: PowerPoint[];
+  machineType: string;
+  matchedCpuProfile?: string;
+  memoryGb: number;
+  platformCpu?: string;
+  scope3EmissionsHourly?: number;
+  vcpus: number;
+}
+
+export interface ZoneMapping {
+  carbonIntensityUrl: string;
+  pue: number;
+  zone: string;
+}
+
+export interface CarbonResult {
+  carbonIntensity: number;
+  cpuEmissions: number;
+  cpuEnergyKwh: number;
+  machineType: string;
+  provider: CloudProvider;
+  pue: number;
+  ramEmissions: number;
+  ramEnergyKwh: number;
+  region: string;
+  runtimeHours: number;
+  scope3Emissions: number;
+  totalEmissions: number;
+  zone: string;
+}
+
+export interface EmissionsRecord {
+  created_at: string;
+  job_id: number;
+  machine_type: string;
+  pipeline_id: number;
+  project_id: number;
+  region: string;
+  runtime_seconds: number;
+  total_emissions: number;
+  total_energy_kwh: number;
+}