@nikeandocean/carbon-factor-matcher 0.3.0 → 2.1.0

package/README.md

@@ -1,13 +1,17 @@
+[![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.
+An MCP (Model Context Protocol) server that connects AI agents with carbon emission factor 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:
+Carbon Factor Matcher helps AI agents find the most appropriate emission factors from standardized environmental databases. It uses a hybrid search algorithm:
+
+1. **Keyword + Embedding retrieval** — Field-weighted keyword scoring and semantic similarity to find candidate factors
+2. **Quality-based ranking** — 5-dimension data quality assessment to rank candidates
 
-1. **Embedding-based rough filtering** — Semantic similarity to find candidate factors
-2. **LLM-based fine ranking** — AI-powered selection with reasoning and confidence scores
+The calling AI agent selects the best match from the ranked candidates. No external LLM API needed.
 
 ### Supported Databases
 
@@ -18,6 +22,7 @@ Carbon Factor Matcher helps AI agents and LLM-based applications find the most a
 
 - 5-dimension data quality rating (technology, geography, source, time, factor type)
 - Multi-language support (Chinese/English activity descriptions)
+- Zero configuration — works out of the box after installation
 - MCP-compatible — works with Claude, Cursor, Windsurf, Cline, Continue, and any MCP client
 
 ## Installation
@@ -124,7 +129,7 @@ The Free tier works immediately after installation (300 queries/day, ELCD databa
 | 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 |
+| **Pro** | $5 (one-time) | ELCD + ecoinvent (~21,000 factors), hybrid matching with quality rating, unlimited queries |
 
 ### Purchase License Key
 
@@ -139,10 +144,7 @@ After purchase, you'll receive a license key via email. Set it as an environment
       "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"
+        "CARBON_FACTOR_LICENSE_KEY": "PRO-xxxx-xxxx"
       }
     }
   }
@@ -154,16 +156,15 @@ After purchase, you'll receive a license key via email. Set it as an environment
 | 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` |
 
+Note: No external LLM API configuration needed. The calling AI agent handles final factor selection.
+
 ## 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.
+Match activity data to emission factors. Free tier uses keyword search; Pro tier uses hybrid embedding + quality ranking. Returns ranked candidates for the calling agent to select from.
 
 **Input:**
 ```json
@@ -173,18 +174,22 @@ Match activity data to the best emission factor. Free tier uses keyword search;
 }
 ```
 
-**Output:**
+**Output (Pro tier):**
 ```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": [...]
+  "candidates": [
+    {
+      "id": "elec-cn-south-10kv-2024",
+      "name": "Electricity, 10kV, South China Grid",
+      "value": 0.6101,
+      "unit": "kgCO2e/kWh",
+      "hybrid_score": 0.85,
+      "quality_ratings": {"tech_representativeness": 1, "source_reliability": 1, "...": "..."},
+      "quality_score": 0.9,
+      "final_score": 0.875
+    }
+  ],
+  "selection_guidance": "从候选列表中选择最匹配的排放因子..."
 }
 ```
 
@@ -220,12 +225,11 @@ Get full metadata for a specific factor.
 
 - 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/tra121vel/carbon-factor-matcher/issues
+- **Issues:** https://github.com/nikeandocean/carbon-factor-matcher/issues
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nikeandocean/carbon-factor-matcher",
-  "version": "0.3.0",
-  "description": "MCP server for intelligent emission factor matching — connects LLMs with carbon emission factor databases (ELCD, ecoinvent)",
+  "version": "2.1.0",
+  "description": "MCP server for intelligent emission factor matching — connects AI agents with carbon emission factor databases (ELCD, ecoinvent)",
   "main": "index.js",
   "bin": {
     "carbon-factor-matcher": "index.js"
@@ -31,8 +31,16 @@
     "carbon-footprint",
     "co2"
   ],
-  "author": "tra121vel",
+  "author": "nikeandocean",
   "license": "Proprietary",
+  "homepage": "https://github.com/nikeandocean/carbon-factor-matcher#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikeandocean/carbon-factor-matcher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nikeandocean/carbon-factor-matcher/issues"
+  },
   "dependencies": {},
   "engines": {
     "node": ">=18.0.0"