carbon-factor-matcher 1.0.9__tar.gz

carbon_factor_matcher-1.0.9/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+
+# Virtual environment
+.venv/
+venv/
+
+# Data files
+*.zolca
+*.zip
+data/factors/*.json
+data/factors/processes/
+data/factors/flows/
+data/factors/unit_groups/
+data/factors/flow_properties/
+data/factors/lcia_categories/
+data/factors/locations/
+data/factors/sources/
+data/factors/actors/
+data/factors/bin/
+data/factors/currencies/
+data/factors/dq_systems/
+data/factors/lcia_methods/
+!data/factors/.gitkeep
+
+# Environment
+.env
+.env.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+usage.db
+
+# Workers
+workers/.wrangler/
+workers/factors.json
+workers/node_modules/

carbon_factor_matcher-1.0.9/CLAUDE.md

@@ -0,0 +1,189 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Carbon Factor Matcher is a **commercial MCP server** that connects LLMs with carbon emission factor databases (ELCD, ecoinvent 3.10). It uses a two-stage hybrid search algorithm: embedding-based rough filtering + LLM-based fine ranking with 5-dimension data quality assessment. Licensed under a Free/Pro tier model ($5 one-time for Pro).
+
+## Build & Run
+
+```bash
+# Install for development (editable)
+pip install -e .
+
+# Run the MCP server
+python -m carbon_factor_matcher
+# or
+carbon-factor-matcher
+
+# Run all tests
+pytest
+
+# Run a single test file
+pytest tests/test_license.py
+
+# Run a single test class or method
+pytest tests/test_license.py::TestLicenseManager::test_pro_key
+```
+
+## Architecture
+
+### Core Pipeline (matcher.py)
+
+`EmissionFactorMatcher` implements the full matching pipeline:
+
+- **Stage 0 — Unit pre-filter**: Hard constraint filtering by unit compatibility (supports Chinese/English unit aliases like `kWh` ↔ `千瓦时` ↔ `度`)
+- **Stage 1 — Hybrid retrieval**: Keyword scoring (weight 0.3) + embedding similarity (weight 0.7). Optimization: keyword pre-filters to `keyword_top_n` candidates before computing expensive embeddings
+- **Stage 2 — LLM fine ranking**: Sends candidates with quality ratings to DeepSeek/OpenAI for final selection. Falls back to hybrid scores on LLM failure
+
+Embedding model: `shibing624/text2vec-base-chinese` (sentence-transformers, runs on CPU). Embeddings are lazily cached per factor index.
+
+### Data Layer
+
+- **`models.py`**: Core dataclasses — `Factor`, `Activity`, `MatchResult`
+- **`factor_db.py`**: `FactorDatabase` loads factors from JSON-LD ILCD files (bundled in `data/factors/`) and compressed `.json.gz`. Supports adapter pattern via `load_adapter()`
+- **`adapters/base.py`**: Abstract `FactorAdapter` base class
+- **`adapters/ecoinvent.py`**: `EcoinventExcelAdapter` loads ecoinvent Database Overview Excel files (requires openpyxl)
+
+### MCP Server (server.py)
+
+`create_server()` wires everything together. Three MCP tools exposed:
+- `factor_match` — Two-stage matching (Pro) or basic keyword search (Free)
+- `factor_search` — Keyword search with category filter
+- `factor_detail` — Full metadata for a specific factor
+
+### Commercial Layer
+
+- **`license.py`**: `LicenseManager` parses license key prefix (`PRO-*` → Pro tier). Free tier: 300 queries/day, no license key needed. Pro: unlimited queries + LLM matching
+- **`usage_tracker.py`**: SQLite-based daily call tracking per user (hashed license key)
+- **`api_client.py`**: `FactorAPIClient` queries the remote Cloudflare Worker API for factor data (no local database needed for end users)
+
+### Configuration
+
+All config via environment variables (resolved in `server.py:create_server()`):
+
+| Variable | Default |
+|---|---|
+| `CARBON_FACTOR_DATA_DIR` | `data/factors` (bundled) |
+| `CARBON_FACTOR_LICENSE_KEY` | empty (Free) |
+| `LLM_API_KEY` | — |
+| `LLM_BASE_URL` | `https://api.deepseek.com` |
+| `LLM_MODEL` | `deepseek-chat` |
+| `EMBEDDING_MODEL` | `shibing624/text2vec-base-chinese` |
+
+### npm Distribution
+
+`index.js` is a Node.js wrapper that calls `python -m carbon_factor_matcher` via subprocess. Published to npm as `@nikeandocean/carbon-factor-matcher`. The `package.json` has no JS dependencies — it's purely a launcher.
+
+## Commercial Infrastructure
+
+### Cloudflare Worker (`workers/paddle-webhook.js`)
+
+The Worker handles three responsibilities: checkout, webhook processing, and factor data API.
+
+**Endpoints:**
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/api/search?q=&category=&limit=` | GET | Keyword search over factors |
+| `/api/factor/{id}` | GET | Full metadata for one factor |
+| `/api/stats` | GET | Category breakdown + total count |
+| `/checkout?email=` | GET | Create Paddle checkout, redirect to hosted page |
+| `/webhook` | POST | Process Paddle events, generate license key, send email |
+
+**Deploy:** `cd workers && npx wrangler deploy`
+
+**Config (Cloudflare Secrets):**
+- `PADDLE_API_KEY` — Paddle seller API key
+- `PADDLE_WEBHOOK_SECRET` — Webhook signature verification
+- `RESEND_API_KEY` — Email service API key
+- `PADDLE_PRICE_ID` — Price object ID for checkout (format: `pri_xxxxx`)
+
+**R2 Binding:** `CARBON_FACTORS` → bucket `carbon-factors`, key `factors.json`
+
+### Data Processing (`workers/process_data.py`)
+
+Converts raw JSON-LD files into a single `factors.json`:
+
+```bash
+cd workers
+python process_data.py  # reads ../data/factors/processes/*.json, writes factors.json
+# Upload to R2:
+npx wrangler r2 object put carbon-factors/factors.json --file factors.json --remote
+```
+
+Factor fields extracted: `id`, `name`, `category`, `value`, `unit`, `geography`, `source`, `year`, `applicability`, `quality_*` (5-dimension ratings).
+
+Note: ELCD has ~600 factors, ecoinvent has ~21,000. The `process_data.py` reads from `data/factors/processes/` (ecoinvent).
+
+### Paddle Integration Lessons
+
+- **Paddle CDN (`cdn.paddle.com`) is blocked in China** via CloudFront. Do NOT use the Paddle JS SDK checkout popup.
+- **Solution:** Server-side Paddle API (`POST https://api.paddle.com/transactions`) creates a checkout session, then redirect to `https://checkout.paddle.com/checkout/custom/{transaction_id}`. No client-side JS needed.
+- **Price ID** is created in Paddle dashboard, not in code. Format: `pri_xxxxx`.
+- **Webhook events** must verify HMAC signature using `paddle-webhook` secret.
+- **Idempotency**: Processed transactions are stored in R2 at `processed/{txn_id}` to prevent duplicate license key generation on Paddle retries.
+
+### GitHub Pages (public branch)
+
+- `index.html` — Purchase page, links to Worker `/checkout` endpoint
+- `demo.html` — Standalone demo with 30+ hardcoded ELCD factors, client-side search
+- `TERMS.md`, `PRIVACY.md`, `REFUND.md` — Required by Paddle for compliance
+- No Python code or data files on the public branch (`.gitignore` enforces this)
+
+## Key Domain Concepts
+
+- **Emission factor**: CO2-equivalent per unit activity (e.g., kgCO2e/kWh for electricity)
+- **5-dimension quality rating**: technology representativeness (0.3), source reliability (0.4), geographic representativeness (0.1), time representativeness (0.1), factor type (0.1). Lower rating number = better quality (1=优, 2=中, 3=差)
+- **ELCD**: European Reference Life Cycle Database — ~600 factors, source JSON-LD files in `data/factors/`. Processed to `factors.json` and hosted on Cloudflare R2
+- **ecoinvent**: Commercial Swiss LCA database — ~21,000 factors pre-imported as JSON in `data/factors/processes/`, Pro-only. Additional data can be loaded via Excel adapter
+
+## Testing Patterns
+
+Tests use pytest with `asyncio_mode = "auto"`. Test files follow `test_*.py` naming. The `eval_*.py` files are evaluation scripts (not standard unit tests) for benchmarking matcher quality.
+
+## Git Workflow — Dual Branch Strategy
+
+This repo uses a **dual-branch** approach to keep core code private while maintaining a public GitHub page for commercial purposes.
+
+### Branch Layout
+
+| Branch | Content | Remote Tracking |
+|--------|---------|-----------------|
+| `master` | Full Python codebase (source, tests, data) | **None** — no upstream, safe from accidental push |
+| `public` | README + policy files + LICENSE only | `origin/master` — the actual GitHub page |
+
+### Why
+
+GitHub serves as the product landing page for Paddle compliance (Terms, Privacy, Refund policies). Core code must not be exposed. The `master` branch has no remote tracking to prevent accidental `git push`.
+
+### Common Operations
+
+```bash
+# Update GitHub public page
+git checkout public
+# edit README.md, TERMS.md, etc.
+git add . && git commit -m "docs: ..."
+git push public
+
+# Switch back to development
+git checkout master
+```
+
+### Important Notes
+
+- **Never force-push `master` to origin** — it would overwrite the public page
+- **`git push` on master will fail** (no upstream) — this is intentional
+- The `public` branch is an orphan branch (no shared history with `master`)
+- SSH is configured for GitHub via Clash SOCKS5 proxy on port 7897 (`~/.ssh/config`)
+- `workers/factors.json` is not committed — lives in Cloudflare R2 only
+- `workers/node_modules/` and `workers/.wrangler/` are gitignored
+- The `workers/` directory must never appear on the `public` branch
+
+## Network & Proxy
+
+- Direct HTTPS to GitHub is blocked; use SSH with SOCKS5 proxy
+- SSH config at `~/.ssh/config` routes `github.com` through `connect -S 127.0.0.1:7897`
+- Clash proxy port: **7897** (not the default 7891 — verify with `netstat -an | grep 789` if connection fails)
+- If `git push` times out, check that Clash is running and the port matches

carbon_factor_matcher-1.0.9/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include data/factors *.json

carbon_factor_matcher-1.0.9/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: carbon-factor-matcher
+Version: 1.0.9
+Summary: MCP server for intelligent emission factor matching using LLM-powered semantic search
+Project-URL: Homepage, https://github.com/nikeandocean/carbon-factor-matcher
+License: Proprietary
+Keywords: carbon,carbon-accounting,carbon-footprint,climate,ecoinvent,elcd,emission-factor,esg,ghg,lca,life-cycle-assessment,mcp,mcp-server,sustainability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: sentence-transformers>=3.0.0
+Description-Content-Type: text/markdown
+
+[![smithery badge](https://smithery.ai/badge/nikeandocean/carbon-factor-matcher)](https://smithery.ai/servers/nikeandocean/carbon-factor-matcher)
+
+# 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"
+}
+```
+
+## Demo
+
+👉 **[Try the Live Demo](https://nikeandocean.github.io/carbon-factor-matcher/demo.html)** — Search 30+ emission factors directly in your browser (no installation needed).
+
+## System Requirements
+
+- Node.js 18+ (for `npx`)
+- Python 3.11+ (auto-installed via pip)
+- LLM API key (Pro tier only — DeepSeek recommended)
+
+## Support
+
+- **Email:** tao.yan@zju.edu.cn
+- **Issues:** https://github.com/nikeandocean/carbon-factor-matcher/issues
+
+## License
+
+This is proprietary software. See [LICENSE](LICENSE) for details.
+
+---
+
+© 2024 Carbon Factor Matcher. All rights reserved.

carbon_factor_matcher-1.0.9/PRIVACY.md

@@ -0,0 +1,3 @@
+# Privacy Policy
+
+We value your privacy. Carbon Factor Matcher does not collect, store, or share any personal user data or environmental query information. Your license key validation is processed securely via Paddle, and no personal identifiable information (PII) is transferred to our servers.