@nikeandocean/carbon-factor-matcher 0.2.0

package/README.md

@@ -0,0 +1,252 @@
+# Carbon Factor Matcher — MCP Server for Carbon Accounting
+
+An MCP (Model Context Protocol) server that connects LLMs with carbon footprint databases. It provides intelligent emission factor matching for carbon accounting, LCA (Life Cycle Assessment), and ESG reporting applications.
+
+## What is this MCP?
+
+Carbon Factor Matcher helps AI agents and LLM-based applications find the most appropriate emission factors from standardized environmental databases. It uses a two-stage hybrid search algorithm:
+
+1. **Embedding-based rough filtering** — Semantic similarity to find candidate factors
+2. **LLM-based fine ranking** — AI-powered selection with reasoning and confidence scores
+
+### Supported Databases
+
+- **ELCD** — European Reference Life Cycle Database (~600 factors, included in Free tier)
+- **ecoinvent 3.10** — Swiss Centre for Life Cycle Inventories (~21,000 factors, Pro license required)
+
+### Key Features
+
+- 5-dimension data quality rating (technology, geography, source, time, factor type)
+- Multi-language support (Chinese/English activity descriptions)
+- MCP-compatible — works with Claude, Cursor, Windsurf, Cline, Continue, and any MCP client
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add carbon-factor-matcher -- npx -y @nikeandocean/carbon-factor-matcher
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "carbon-factor-matcher": {
+      "command": "npx",
+      "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
+    }
+  }
+}
+```
+
+Config file locations:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor
+
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "carbon-factor-matcher": {
+      "command": "npx",
+      "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
+    }
+  }
+}
+```
+
+Or via Cursor UI: **Settings → MCP → Add new global MCP server**.
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "carbon-factor-matcher": {
+      "command": "npx",
+      "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
+    }
+  }
+}
+```
+
+Or via Windsurf UI: **Settings → Cascade → MCP Servers → Add**.
+
+### Cline (VS Code Extension)
+
+Add to Cline MCP settings (click **MCP Servers** icon in Cline panel):
+
+```json
+{
+  "mcpServers": {
+    "carbon-factor-matcher": {
+      "command": "npx",
+      "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
+    }
+  }
+}
+```
+
+### Continue (VS Code / JetBrains)
+
+Add to `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: carbon-factor-matcher
+    command: npx
+    args:
+      - "-y"
+      - "@nikeandocean/carbon-factor-matcher"
+```
+
+### Smithery.ai (One-Click Install)
+
+```bash
+npx -y smithery mcp add nikeandocean/carbon-factor-matcher
+```
+
+Or visit [smithery.ai/server/@nikeandocean/carbon-factor-matcher](https://smithery.ai/server/@nikeandocean/carbon-factor-matcher) for hosted endpoint.
+
+## Pro License
+
+The Free tier works immediately after installation (300 queries/day, ELCD database, keyword search). To unlock the full experience:
+
+| Plan | Price | Features |
+|------|-------|----------|
+| **Free** | $0 | ELCD database (~600 factors), keyword search, 300 queries/day |
+| **Pro** | $5 (one-time) | ELCD + ecoinvent (~21,000 factors), LLM-powered matching, unlimited queries, data quality rating |
+
+### Purchase License Key
+
+👉 **[Buy Pro License](https://nikeandocean.github.io/carbon-factor-matcher)**
+
+After purchase, you'll receive a license key via email. Set it as an environment variable in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "carbon-factor-matcher": {
+      "command": "npx",
+      "args": ["-y", "@nikeandocean/carbon-factor-matcher"],
+      "env": {
+        "CARBON_FACTOR_LICENSE_KEY": "PRO-xxxx-xxxx",
+        "LLM_API_KEY": "sk-xxxx",
+        "LLM_BASE_URL": "https://api.deepseek.com",
+        "LLM_MODEL": "deepseek-chat"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CARBON_FACTOR_LICENSE_KEY` | Your license key (empty = Free tier) | — |
+| `LLM_API_KEY` | LLM API key for Pro matching (DeepSeek/OpenAI) | — |
+| `LLM_BASE_URL` | LLM endpoint URL | `https://api.deepseek.com` |
+| `LLM_MODEL` | LLM model name | `deepseek-chat` |
+| `CARBON_FACTOR_DATA_DIR` | Path to local factor database | `data/factors` |
+
+## Available Tools
+
+### `factor_match`
+
+Match activity data to the best emission factor. Free tier uses keyword search; Pro tier uses hybrid embedding + LLM matching with quality assessment.
+
+**Input:**
+```json
+{
+  "activity_data": "Factory in Shenzhen, 10kV industrial electricity, 2024, semiconductor fab",
+  "top_k": 10
+}
+```
+
+**Output:**
+```json
+{
+  "selected_factor": {
+    "id": "elec-cn-south-10kv-2024",
+    "name": "Electricity, 10kV, South China Grid",
+    "value": 0.6101,
+    "unit": "kgCO2e/kWh"
+  },
+  "confidence": 0.92,
+  "reason": "Best match for industrial electricity in South China region",
+  "alternatives": [...]
+}
+```
+
+### `factor_search`
+
+Search emission factors by keyword with optional filters.
+
+**Input:**
+```json
+{
+  "query": "diesel",
+  "category": "fuel",
+  "limit": 10
+}
+```
+
+### `factor_detail`
+
+Get full metadata for a specific factor.
+
+**Input:**
+```json
+{
+  "factor_id": "elec-cn-south-10kv-2024"
+}
+```
+
+## System Requirements
+
+- Node.js 18+ (for `npx`)
+- Python 3.11+ (auto-installed via pip)
+- LLM API key (Pro tier only — DeepSeek recommended)
+
+## Tech Stack
+
+- **MCP SDK** — Model Context Protocol implementation
+- **Sentence Transformers** — Semantic embedding (shibing624/text2vec-base-chinese)
+- **DeepSeek/OpenAI** — LLM-based factor ranking
+- **SQLite** — Usage tracking
+- **Cloudflare Workers** — API and webhook processing
+- **Paddle** — Payment processing
+
+## Discovery
+
+This MCP server is available on:
+
+| Platform | Link | Status |
+|----------|------|--------|
+| **npm** | [@nikeandocean/carbon-factor-matcher](https://www.npmjs.com/package/@nikeandocean/carbon-factor-matcher) | Published |
+| **Smithery.ai** | [smithery.ai/server/@nikeandocean/carbon-factor-matcher](https://smithery.ai/server/@nikeandocean/carbon-factor-matcher) | Listed |
+| **mcp.so** | [mcp.so](https://mcp.so) | Submit via site |
+| **Glama.ai** | [glama.ai/mcp/servers](https://glama.ai/mcp/servers) | Auto-indexed from npm |
+
+## Support
+
+- **Email:** tao.yan@zju.edu.cn
+- **Issues:** https://github.com/tra121vel/carbon-factor-matcher/issues
+
+## License
+
+This is proprietary software. See [LICENSE](LICENSE) for details.
+
+---
+
+© 2024 Carbon Factor Matcher. All rights reserved.

package/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+/**
+ * Carbon Factor Matcher - MCP Server
+ *
+ * npm wrapper that launches the Python MCP server.
+ * Requires: Python 3.11+, pip install carbon-factor-matcher
+ */
+
+const { execSync, spawn } = require('child_process');
+
+// Check if Python is available
+try {
+  execSync('python --version', { stdio: 'ignore' });
+} catch (e) {
+  console.error('Error: Python 3.11+ is required to run carbon-factor-matcher');
+  console.error('Install from https://www.python.org/downloads/');
+  process.exit(1);
+}
+
+// Launch the MCP server
+const child = spawn('python', ['-m', 'carbon_factor_matcher'], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nikeandocean/carbon-factor-matcher",
+  "version": "0.2.0",
+  "description": "MCP server for intelligent emission factor matching — connects LLMs with carbon emission factor databases (ELCD, ecoinvent)",
+  "main": "index.js",
+  "bin": {
+    "carbon-factor-matcher": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src/carbon_factor_matcher/**/*.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "carbon",
+    "emission-factor",
+    "carbon-accounting",
+    "lca",
+    "life-cycle-assessment",
+    "ecoinvent",
+    "elcd",
+    "sustainability",
+    "climate",
+    "esg",
+    "ghg",
+    "carbon-footprint",
+    "co2"
+  ],
+  "author": "tra121vel",
+  "license": "Proprietary",
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/carbon_factor_matcher/__init__.py

@@ -0,0 +1,3 @@
+"""Carbon Factor Matcher - MCP server for intelligent emission factor matching."""
+
+__version__ = "0.1.0"

package/src/carbon_factor_matcher/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m carbon_factor_matcher`."""
+
+from carbon_factor_matcher.server import main
+
+main()

package/src/carbon_factor_matcher/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Factor database adapters for different data source formats."""
+
+from carbon_factor_matcher.adapters.base import FactorAdapter
+from carbon_factor_matcher.adapters.ecoinvent import EcoinventExcelAdapter
+
+__all__ = ["FactorAdapter", "EcoinventExcelAdapter"]

package/src/carbon_factor_matcher/adapters/base.py

@@ -0,0 +1,22 @@
+"""Base class for factor database adapters."""
+
+from abc import ABC, abstractmethod
+
+from carbon_factor_matcher.models import Factor
+
+
+class FactorAdapter(ABC):
+    """Abstract base class for loading emission factors from different data sources.
+
+    Each adapter knows how to parse a specific format (ELCD JSON-LD,
+    ecoinvent Excel, EcoSpold2 XML, etc.) and return a list of Factor objects.
+    """
+
+    @abstractmethod
+    def load(self) -> list[Factor]:
+        """Load all factors from the data source.
+
+        Returns:
+            List of Factor objects ready for matching.
+        """
+        ...

package/src/carbon_factor_matcher/adapters/ecoinvent.py

@@ -0,0 +1,292 @@
+"""Adapter for ecoinvent Database Overview Excel files.
+
+Loads activity metadata from the ecoinvent Excel export and converts
+them into Factor objects for matching. CO2 values are placeholders (0.0)
+until Phase 2 fills them from the actual database.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from carbon_factor_matcher.adapters.base import FactorAdapter
+from carbon_factor_matcher.models import Factor
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ImportResult:
+    """Result of an ecoinvent import operation."""
+    total_rows: int = 0
+    imported: int = 0
+    skipped: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate import success rate."""
+        if self.total_rows == 0:
+            return 0.0
+        return self.imported / self.total_rows
+
+# Sheet names for different system models
+SYSTEM_MODEL_SHEETS = {
+    "cut-off": "Cut-Off AO",
+    "cutoff": "Cut-Off AO",
+    "undefined": "Undefined AO",
+    "apos": "APOS AO",
+    "consequential": "Consequential AO",
+    "en15804": "EN15804 AO",
+}
+
+# Sectors to skip (not useful for emission factor matching)
+SKIP_SECTORS = {
+    "Waste Treatment & Recycling",
+}
+
+
+class EcoinventExcelAdapter(FactorAdapter):
+    """Load ecoinvent factors from the Database Overview Excel file.
+
+    Args:
+        excel_path: Path to the ecoinvent Excel file.
+        system_model: System model to load. One of: "cut-off", "undefined",
+            "apos", "consequential", "en15804". Default: "cut-off".
+        sectors: Optional list of sectors to include. If None, includes all.
+        geographies: Optional list of geography codes to include. If None, includes all.
+    """
+
+    def __init__(
+        self,
+        excel_path: str,
+        system_model: str = "cut-off",
+        sectors: list[str] | None = None,
+        geographies: list[str] | None = None,
+    ):
+        self._path = Path(excel_path)
+        if not self._path.exists():
+            raise FileNotFoundError(f"Excel file not found: {excel_path}")
+
+        sheet_name = SYSTEM_MODEL_SHEETS.get(system_model.lower())
+        if sheet_name is None:
+            raise ValueError(
+                f"Unknown system model '{system_model}'. "
+                f"Choose from: {list(SYSTEM_MODEL_SHEETS.keys())}"
+            )
+        self._sheet_name = sheet_name
+        self._sectors = set(sectors) if sectors else None
+        self._geographies = set(geographies) if geographies else None
+
+    def load(self) -> list[Factor]:
+        """Load factors from the Excel file."""
+        try:
+            import openpyxl
+        except ImportError:
+            raise ImportError(
+                "openpyxl is required for ecoinvent Excel adapter. "
+                "Install it with: pip install openpyxl"
+            )
+
+        logger.info(f"Loading ecoinvent from {self._path.name}, sheet={self._sheet_name}")
+        wb = openpyxl.load_workbook(self._path, read_only=True, data_only=True)
+
+        if self._sheet_name not in wb.sheetnames:
+            wb.close()
+            raise ValueError(
+                f"Sheet '{self._sheet_name}' not found. "
+                f"Available: {wb.sheetnames}"
+            )
+
+        ws = wb[self._sheet_name]
+        headers = [cell.value for cell in next(ws.iter_rows(min_row=1, max_row=1))]
+        col_map = {h: i for i, h in enumerate(headers) if h}
+
+        factors = []
+        skipped = 0
+
+        for row in ws.iter_rows(min_row=2, values_only=True):
+            row_list = list(row)
+
+            # Extract fields by header name
+            activity_uuid = self._get_col(row_list, col_map, "Activity UUID")
+            activity_name = self._get_col(row_list, col_map, "Activity Name")
+            geography = self._get_col(row_list, col_map, "Geography")
+            time_period = self._get_col(row_list, col_map, "Time Period")
+            sector = self._get_col(row_list, col_map, "Sector")
+            product_name = self._get_col(row_list, col_map, "Reference Product Name")
+            unit = self._get_col(row_list, col_map, "Unit")
+            isic = self._get_col(row_list, col_map, "ISIC Classification")
+
+            # Skip if missing essential fields
+            if not activity_uuid or not activity_name:
+                skipped += 1
+                continue
+
+            # Skip waste/infrastructure sectors
+            if sector in SKIP_SECTORS:
+                skipped += 1
+                continue
+
+            # Apply filters
+            if self._sectors and sector not in self._sectors:
+                skipped += 1
+                continue
+            if self._geographies and geography not in self._geographies:
+                skipped += 1
+                continue
+
+            # Parse year from time period (e.g., "2019 - 2023" → 2019)
+            source_year = self._parse_year(time_period)
+
+            # Build applicability from product info
+            applicability = product_name or activity_name
+
+            # Build category from sector + ISIC
+            category = sector or ""
+            if isic:
+                category = f"{sector}/{isic}" if sector else isic
+
+            factor = Factor(
+                id=activity_uuid,
+                name=activity_name,
+                category=category,
+                value=0.0,  # Placeholder — Phase 2 fills CO2 values
+                unit=unit or "",
+                geography={"location": geography or ""},
+                applicability=applicability,
+                source="ecoinvent 3.10",
+                source_year=source_year,
+                raw_data={
+                    "product_name": product_name,
+                    "isic": isic,
+                    "time_period": time_period,
+                    "system_model": self._sheet_name,
+                },
+            )
+            factors.append(factor)
+
+        wb.close()
+        logger.info(f"Loaded {len(factors)} ecoinvent factors (skipped {skipped})")
+        return factors
+
+    def load_with_result(self) -> tuple[list[Factor], ImportResult]:
+        """Load factors and return detailed import result.
+
+        Returns:
+            Tuple of (factors_list, import_result).
+        """
+        try:
+            import openpyxl
+        except ImportError:
+            raise ImportError(
+                "openpyxl is required for ecoinvent Excel adapter. "
+                "Install it with: pip install openpyxl"
+            )
+
+        logger.info(f"Loading ecoinvent from {self._path.name}, sheet={self._sheet_name}")
+        wb = openpyxl.load_workbook(self._path, read_only=True, data_only=True)
+
+        if self._sheet_name not in wb.sheetnames:
+            wb.close()
+            raise ValueError(
+                f"Sheet '{self._sheet_name}' not found. "
+                f"Available: {wb.sheetnames}"
+            )
+
+        ws = wb[self._sheet_name]
+        headers = [cell.value for cell in next(ws.iter_rows(min_row=1, max_row=1))]
+        col_map = {h: i for i, h in enumerate(headers) if h}
+
+        factors = []
+        errors = []
+        total = 0
+        skipped = 0
+
+        for row in ws.iter_rows(min_row=2, values_only=True):
+            total += 1
+            row_list = list(row)
+
+            try:
+                activity_uuid = self._get_col(row_list, col_map, "Activity UUID")
+                activity_name = self._get_col(row_list, col_map, "Activity Name")
+                geography = self._get_col(row_list, col_map, "Geography")
+                time_period = self._get_col(row_list, col_map, "Time Period")
+                sector = self._get_col(row_list, col_map, "Sector")
+                product_name = self._get_col(row_list, col_map, "Reference Product Name")
+                unit = self._get_col(row_list, col_map, "Unit")
+                isic = self._get_col(row_list, col_map, "ISIC Classification")
+
+                if not activity_uuid or not activity_name:
+                    skipped += 1
+                    continue
+
+                if sector in SKIP_SECTORS:
+                    skipped += 1
+                    continue
+
+                if self._sectors and sector not in self._sectors:
+                    skipped += 1
+                    continue
+                if self._geographies and geography not in self._geographies:
+                    skipped += 1
+                    continue
+
+                source_year = self._parse_year(time_period)
+                applicability = product_name or activity_name
+                category = sector or ""
+                if isic:
+                    category = f"{sector}/{isic}" if sector else isic
+
+                factor = Factor(
+                    id=activity_uuid,
+                    name=activity_name,
+                    category=category,
+                    value=0.0,
+                    unit=unit or "",
+                    geography={"location": geography or ""},
+                    applicability=applicability,
+                    source="ecoinvent 3.10",
+                    source_year=source_year,
+                    raw_data={
+                        "product_name": product_name,
+                        "isic": isic,
+                        "time_period": time_period,
+                        "system_model": self._sheet_name,
+                    },
+                )
+                factors.append(factor)
+
+            except Exception as e:
+                errors.append(f"Row {total}: {str(e)}")
+
+        wb.close()
+
+        result = ImportResult(
+            total_rows=total,
+            imported=len(factors),
+            skipped=skipped,
+            errors=errors,
+        )
+        logger.info(f"Loaded {len(factors)} ecoinvent factors (skipped {skipped})")
+
+        return factors, result
+
+    @staticmethod
+    def _get_col(row: list, col_map: dict, header: str) -> str | None:
+        """Get a column value by header name."""
+        idx = col_map.get(header)
+        if idx is None or idx >= len(row):
+            return None
+        val = row[idx]
+        return str(val).strip() if val else None
+
+    @staticmethod
+    def _parse_year(time_period: str) -> int:
+        """Extract start year from time period string like '2019 - 2023'."""
+        if not time_period:
+            return 0
+        try:
+            return int(time_period[:4])
+        except (ValueError, IndexError):
+            return 0