@nikeandocean/carbon-factor-matcher 0.2.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +240 -236
  2. package/index.js +47 -47
  3. package/package.json +11 -3
package/README.md CHANGED
@@ -1,236 +1,240 @@
1
- # Carbon Factor Matcher — MCP Server for Carbon Accounting
2
-
3
- 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.
4
-
5
- ## What is this MCP?
6
-
7
- 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:
8
-
9
- 1. **Embedding-based rough filtering** — Semantic similarity to find candidate factors
10
- 2. **LLM-based fine ranking** — AI-powered selection with reasoning and confidence scores
11
-
12
- ### Supported Databases
13
-
14
- - **ELCD** — European Reference Life Cycle Database (~600 factors, included in Free tier)
15
- - **ecoinvent 3.10** — Swiss Centre for Life Cycle Inventories (~21,000 factors, Pro license required)
16
-
17
- ### Key Features
18
-
19
- - 5-dimension data quality rating (technology, geography, source, time, factor type)
20
- - Multi-language support (Chinese/English activity descriptions)
21
- - MCP-compatible — works with Claude, Cursor, Windsurf, Cline, Continue, and any MCP client
22
-
23
- ## Installation
24
-
25
- ### Claude Code
26
-
27
- ```bash
28
- claude mcp add carbon-factor-matcher -- npx -y @nikeandocean/carbon-factor-matcher
29
- ```
30
-
31
- ### Claude Desktop
32
-
33
- Add to `claude_desktop_config.json`:
34
-
35
- ```json
36
- {
37
- "mcpServers": {
38
- "carbon-factor-matcher": {
39
- "command": "npx",
40
- "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
41
- }
42
- }
43
- }
44
- ```
45
-
46
- Config file locations:
47
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
48
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
49
-
50
- ### Cursor
51
-
52
- Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
53
-
54
- ```json
55
- {
56
- "mcpServers": {
57
- "carbon-factor-matcher": {
58
- "command": "npx",
59
- "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
60
- }
61
- }
62
- }
63
- ```
64
-
65
- Or via Cursor UI: **Settings → MCP → Add new global MCP server**.
66
-
67
- ### Windsurf
68
-
69
- Add to `~/.codeium/windsurf/mcp_config.json`:
70
-
71
- ```json
72
- {
73
- "mcpServers": {
74
- "carbon-factor-matcher": {
75
- "command": "npx",
76
- "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
77
- }
78
- }
79
- }
80
- ```
81
-
82
- Or via Windsurf UI: **Settings → Cascade → MCP Servers → Add**.
83
-
84
- ### Cline (VS Code Extension)
85
-
86
- Add to Cline MCP settings (click **MCP Servers** icon in Cline panel):
87
-
88
- ```json
89
- {
90
- "mcpServers": {
91
- "carbon-factor-matcher": {
92
- "command": "npx",
93
- "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
94
- }
95
- }
96
- }
97
- ```
98
-
99
- ### Continue (VS Code / JetBrains)
100
-
101
- Add to `~/.continue/config.yaml`:
102
-
103
- ```yaml
104
- mcpServers:
105
- - name: carbon-factor-matcher
106
- command: npx
107
- args:
108
- - "-y"
109
- - "@nikeandocean/carbon-factor-matcher"
110
- ```
111
-
112
- ### Smithery.ai (One-Click Install)
113
-
114
- ```bash
115
- npx -y smithery mcp add nikeandocean/carbon-factor-matcher
116
- ```
117
-
118
- Or visit [smithery.ai/server/@nikeandocean/carbon-factor-matcher](https://smithery.ai/server/@nikeandocean/carbon-factor-matcher) for hosted endpoint.
119
-
120
- ## Pro License
121
-
122
- The Free tier works immediately after installation (300 queries/day, ELCD database, keyword search). To unlock the full experience:
123
-
124
- | Plan | Price | Features |
125
- |------|-------|----------|
126
- | **Free** | $0 | ELCD database (~600 factors), keyword search, 300 queries/day |
127
- | **Pro** | $5 (one-time) | ELCD + ecoinvent (~21,000 factors), LLM-powered matching, unlimited queries, data quality rating |
128
-
129
- ### Purchase License Key
130
-
131
- 👉 **[Buy Pro License](https://nikeandocean.github.io/carbon-factor-matcher)**
132
-
133
- After purchase, you'll receive a license key via email. Set it as an environment variable in your MCP config:
134
-
135
- ```json
136
- {
137
- "mcpServers": {
138
- "carbon-factor-matcher": {
139
- "command": "npx",
140
- "args": ["-y", "@nikeandocean/carbon-factor-matcher"],
141
- "env": {
142
- "CARBON_FACTOR_LICENSE_KEY": "PRO-xxxx-xxxx",
143
- "LLM_API_KEY": "sk-xxxx",
144
- "LLM_BASE_URL": "https://api.deepseek.com",
145
- "LLM_MODEL": "deepseek-chat"
146
- }
147
- }
148
- }
149
- }
150
- ```
151
-
152
- ## Configuration
153
-
154
- | Variable | Description | Default |
155
- |----------|-------------|---------|
156
- | `CARBON_FACTOR_LICENSE_KEY` | Your license key (empty = Free tier) | — |
157
- | `LLM_API_KEY` | LLM API key for Pro matching (DeepSeek/OpenAI) | — |
158
- | `LLM_BASE_URL` | LLM endpoint URL | `https://api.deepseek.com` |
159
- | `LLM_MODEL` | LLM model name | `deepseek-chat` |
160
- | `CARBON_FACTOR_DATA_DIR` | Path to local factor database | `data/factors` |
161
-
162
- ## Available Tools
163
-
164
- ### `factor_match`
165
-
166
- Match activity data to the best emission factor. Free tier uses keyword search; Pro tier uses hybrid embedding + LLM matching with quality assessment.
167
-
168
- **Input:**
169
- ```json
170
- {
171
- "activity_data": "Factory in Shenzhen, 10kV industrial electricity, 2024, semiconductor fab",
172
- "top_k": 10
173
- }
174
- ```
175
-
176
- **Output:**
177
- ```json
178
- {
179
- "selected_factor": {
180
- "id": "elec-cn-south-10kv-2024",
181
- "name": "Electricity, 10kV, South China Grid",
182
- "value": 0.6101,
183
- "unit": "kgCO2e/kWh"
184
- },
185
- "confidence": 0.92,
186
- "reason": "Best match for industrial electricity in South China region",
187
- "alternatives": [...]
188
- }
189
- ```
190
-
191
- ### `factor_search`
192
-
193
- Search emission factors by keyword with optional filters.
194
-
195
- **Input:**
196
- ```json
197
- {
198
- "query": "diesel",
199
- "category": "fuel",
200
- "limit": 10
201
- }
202
- ```
203
-
204
- ### `factor_detail`
205
-
206
- Get full metadata for a specific factor.
207
-
208
- **Input:**
209
- ```json
210
- {
211
- "factor_id": "elec-cn-south-10kv-2024"
212
- }
213
- ```
214
-
215
- ## Demo
216
-
217
- 👉 **[Try the Live Demo](https://nikeandocean.github.io/carbon-factor-matcher/demo.html)** — Search 30+ emission factors directly in your browser (no installation needed).
218
-
219
- ## System Requirements
220
-
221
- - Node.js 18+ (for `npx`)
222
- - Python 3.11+ (auto-installed via pip)
223
- - LLM API key (Pro tier only — DeepSeek recommended)
224
-
225
- ## Support
226
-
227
- - **Email:** tao.yan@zju.edu.cn
228
- - **Issues:** https://github.com/tra121vel/carbon-factor-matcher/issues
229
-
230
- ## License
231
-
232
- This is proprietary software. See [LICENSE](LICENSE) for details.
233
-
234
- ---
235
-
236
- © 2024 Carbon Factor Matcher. All rights reserved.
1
+ [![smithery badge](https://smithery.ai/badge/nikeandocean/carbon-factor-matcher)](https://smithery.ai/servers/nikeandocean/carbon-factor-matcher)
2
+
3
+ # Carbon Factor Matcher — MCP Server for Carbon Accounting
4
+
5
+ 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.
6
+
7
+ ## What is this MCP?
8
+
9
+ Carbon Factor Matcher helps AI agents find the most appropriate emission factors from standardized environmental databases. It uses a hybrid search algorithm:
10
+
11
+ 1. **Keyword + Embedding retrieval** — Field-weighted keyword scoring and semantic similarity to find candidate factors
12
+ 2. **Quality-based ranking** — 5-dimension data quality assessment to rank candidates
13
+
14
+ The calling AI agent selects the best match from the ranked candidates. No external LLM API needed.
15
+
16
+ ### Supported Databases
17
+
18
+ - **ELCD** — European Reference Life Cycle Database (~600 factors, included in Free tier)
19
+ - **ecoinvent 3.10** — Swiss Centre for Life Cycle Inventories (~21,000 factors, Pro license required)
20
+
21
+ ### Key Features
22
+
23
+ - 5-dimension data quality rating (technology, geography, source, time, factor type)
24
+ - Multi-language support (Chinese/English activity descriptions)
25
+ - Zero configuration — works out of the box after installation
26
+ - MCP-compatible — works with Claude, Cursor, Windsurf, Cline, Continue, and any MCP client
27
+
28
+ ## Installation
29
+
30
+ ### Claude Code
31
+
32
+ ```bash
33
+ claude mcp add carbon-factor-matcher -- npx -y @nikeandocean/carbon-factor-matcher
34
+ ```
35
+
36
+ ### Claude Desktop
37
+
38
+ Add to `claude_desktop_config.json`:
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "carbon-factor-matcher": {
44
+ "command": "npx",
45
+ "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ Config file locations:
52
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
53
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
54
+
55
+ ### Cursor
56
+
57
+ Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "carbon-factor-matcher": {
63
+ "command": "npx",
64
+ "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ Or via Cursor UI: **Settings → MCP → Add new global MCP server**.
71
+
72
+ ### Windsurf
73
+
74
+ Add to `~/.codeium/windsurf/mcp_config.json`:
75
+
76
+ ```json
77
+ {
78
+ "mcpServers": {
79
+ "carbon-factor-matcher": {
80
+ "command": "npx",
81
+ "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ Or via Windsurf UI: **Settings → Cascade → MCP Servers → Add**.
88
+
89
+ ### Cline (VS Code Extension)
90
+
91
+ Add to Cline MCP settings (click **MCP Servers** icon in Cline panel):
92
+
93
+ ```json
94
+ {
95
+ "mcpServers": {
96
+ "carbon-factor-matcher": {
97
+ "command": "npx",
98
+ "args": ["-y", "@nikeandocean/carbon-factor-matcher"]
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ### Continue (VS Code / JetBrains)
105
+
106
+ Add to `~/.continue/config.yaml`:
107
+
108
+ ```yaml
109
+ mcpServers:
110
+ - name: carbon-factor-matcher
111
+ command: npx
112
+ args:
113
+ - "-y"
114
+ - "@nikeandocean/carbon-factor-matcher"
115
+ ```
116
+
117
+ ### Smithery.ai (One-Click Install)
118
+
119
+ ```bash
120
+ npx -y smithery mcp add nikeandocean/carbon-factor-matcher
121
+ ```
122
+
123
+ Or visit [smithery.ai/server/@nikeandocean/carbon-factor-matcher](https://smithery.ai/server/@nikeandocean/carbon-factor-matcher) for hosted endpoint.
124
+
125
+ ## Pro License
126
+
127
+ The Free tier works immediately after installation (300 queries/day, ELCD database, keyword search). To unlock the full experience:
128
+
129
+ | Plan | Price | Features |
130
+ |------|-------|----------|
131
+ | **Free** | $0 | ELCD database (~600 factors), keyword search, 300 queries/day |
132
+ | **Pro** | $5 (one-time) | ELCD + ecoinvent (~21,000 factors), hybrid matching with quality rating, unlimited queries |
133
+
134
+ ### Purchase License Key
135
+
136
+ 👉 **[Buy Pro License](https://nikeandocean.github.io/carbon-factor-matcher)**
137
+
138
+ After purchase, you'll receive a license key via email. Set it as an environment variable in your MCP config:
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "carbon-factor-matcher": {
144
+ "command": "npx",
145
+ "args": ["-y", "@nikeandocean/carbon-factor-matcher"],
146
+ "env": {
147
+ "CARBON_FACTOR_LICENSE_KEY": "PRO-xxxx-xxxx"
148
+ }
149
+ }
150
+ }
151
+ }
152
+ ```
153
+
154
+ ## Configuration
155
+
156
+ | Variable | Description | Default |
157
+ |----------|-------------|---------|
158
+ | `CARBON_FACTOR_LICENSE_KEY` | Your license key (empty = Free tier) | — |
159
+ | `CARBON_FACTOR_DATA_DIR` | Path to local factor database | `data/factors` |
160
+
161
+ Note: No external LLM API configuration needed. The calling AI agent handles final factor selection.
162
+
163
+ ## Available Tools
164
+
165
+ ### `factor_match`
166
+
167
+ 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.
168
+
169
+ **Input:**
170
+ ```json
171
+ {
172
+ "activity_data": "Factory in Shenzhen, 10kV industrial electricity, 2024, semiconductor fab",
173
+ "top_k": 10
174
+ }
175
+ ```
176
+
177
+ **Output (Pro tier):**
178
+ ```json
179
+ {
180
+ "candidates": [
181
+ {
182
+ "id": "elec-cn-south-10kv-2024",
183
+ "name": "Electricity, 10kV, South China Grid",
184
+ "value": 0.6101,
185
+ "unit": "kgCO2e/kWh",
186
+ "hybrid_score": 0.85,
187
+ "quality_ratings": {"tech_representativeness": 1, "source_reliability": 1, "...": "..."},
188
+ "quality_score": 0.9,
189
+ "final_score": 0.875
190
+ }
191
+ ],
192
+ "selection_guidance": "从候选列表中选择最匹配的排放因子..."
193
+ }
194
+ ```
195
+
196
+ ### `factor_search`
197
+
198
+ Search emission factors by keyword with optional filters.
199
+
200
+ **Input:**
201
+ ```json
202
+ {
203
+ "query": "diesel",
204
+ "category": "fuel",
205
+ "limit": 10
206
+ }
207
+ ```
208
+
209
+ ### `factor_detail`
210
+
211
+ Get full metadata for a specific factor.
212
+
213
+ **Input:**
214
+ ```json
215
+ {
216
+ "factor_id": "elec-cn-south-10kv-2024"
217
+ }
218
+ ```
219
+
220
+ ## Demo
221
+
222
+ 👉 **[Try the Live Demo](https://nikeandocean.github.io/carbon-factor-matcher/demo.html)** — Search 30+ emission factors directly in your browser (no installation needed).
223
+
224
+ ## System Requirements
225
+
226
+ - Node.js 18+ (for `npx`)
227
+ - Python 3.11+ (auto-installed via pip)
228
+
229
+ ## Support
230
+
231
+ - **Email:** tao.yan@zju.edu.cn
232
+ - **Issues:** https://github.com/nikeandocean/carbon-factor-matcher/issues
233
+
234
+ ## License
235
+
236
+ This is proprietary software. See [LICENSE](LICENSE) for details.
237
+
238
+ ---
239
+
240
+ © 2024 Carbon Factor Matcher. All rights reserved.
package/index.js CHANGED
@@ -1,47 +1,47 @@
1
- #!/usr/bin/env node
2
-
3
- /**
4
- * Carbon Factor Matcher - MCP Server
5
- *
6
- * npm wrapper that launches the Python MCP server.
7
- * Auto-installs from PyPI if not already present.
8
- */
9
-
10
- const { execSync, spawn } = require('child_process');
11
-
12
- // Check if Python is available
13
- try {
14
- execSync('python --version', { stdio: 'ignore' });
15
- } catch (e) {
16
- console.error('Error: Python 3.11+ is required to run carbon-factor-matcher');
17
- console.error('Install from https://www.python.org/downloads/');
18
- process.exit(1);
19
- }
20
-
21
- // Ensure the Python package is installed (upgrade if outdated)
22
- try {
23
- execSync('python -c "import carbon_factor_matcher"', { stdio: 'ignore' });
24
- // Package exists, try to upgrade silently
25
- try {
26
- execSync('pip install --upgrade carbon-factor-matcher', { stdio: 'ignore' });
27
- } catch (_) {
28
- // Ignore upgrade failures (offline, permission, etc.)
29
- }
30
- } catch (_) {
31
- console.error('Installing carbon-factor-matcher from PyPI...');
32
- try {
33
- execSync('pip install carbon-factor-matcher', { stdio: 'inherit' });
34
- } catch (e) {
35
- console.error('Failed to install. Run manually: pip install carbon-factor-matcher');
36
- process.exit(1);
37
- }
38
- }
39
-
40
- // Launch the MCP server
41
- const child = spawn('python', ['-m', 'carbon_factor_matcher'], {
42
- stdio: 'inherit',
43
- });
44
-
45
- child.on('exit', (code) => {
46
- process.exit(code || 0);
47
- });
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Carbon Factor Matcher - MCP Server
5
+ *
6
+ * npm wrapper that launches the Python MCP server.
7
+ * Auto-installs from PyPI if not already present.
8
+ */
9
+
10
+ const { execSync, spawn } = require('child_process');
11
+
12
+ // Check if Python is available
13
+ try {
14
+ execSync('python --version', { stdio: 'ignore' });
15
+ } catch (e) {
16
+ console.error('Error: Python 3.11+ is required to run carbon-factor-matcher');
17
+ console.error('Install from https://www.python.org/downloads/');
18
+ process.exit(1);
19
+ }
20
+
21
+ // Ensure the Python package is installed (upgrade if outdated)
22
+ try {
23
+ execSync('python -c "import carbon_factor_matcher"', { stdio: 'ignore' });
24
+ // Package exists, try to upgrade silently
25
+ try {
26
+ execSync('pip install --upgrade carbon-factor-matcher', { stdio: 'ignore' });
27
+ } catch (_) {
28
+ // Ignore upgrade failures (offline, permission, etc.)
29
+ }
30
+ } catch (_) {
31
+ console.error('Installing carbon-factor-matcher from PyPI...');
32
+ try {
33
+ execSync('pip install carbon-factor-matcher', { stdio: 'inherit' });
34
+ } catch (e) {
35
+ console.error('Failed to install. Run manually: pip install carbon-factor-matcher');
36
+ process.exit(1);
37
+ }
38
+ }
39
+
40
+ // Launch the MCP server
41
+ const child = spawn('python', ['-m', 'carbon_factor_matcher'], {
42
+ stdio: 'inherit',
43
+ });
44
+
45
+ child.on('exit', (code) => {
46
+ process.exit(code || 0);
47
+ });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@nikeandocean/carbon-factor-matcher",
3
- "version": "0.2.1",
4
- "description": "MCP server for intelligent emission factor matching — connects LLMs with carbon emission factor databases (ELCD, ecoinvent)",
3
+ "version": "2.0.0",
4
+ "description": "MCP server for intelligent emission factor matching — connects AI agents with carbon emission factor databases (ELCD, ecoinvent)",
5
5
  "main": "index.js",
6
6
  "bin": {
7
7
  "carbon-factor-matcher": "index.js"
@@ -31,8 +31,16 @@
31
31
  "carbon-footprint",
32
32
  "co2"
33
33
  ],
34
- "author": "tra121vel",
34
+ "author": "nikeandocean",
35
35
  "license": "Proprietary",
36
+ "homepage": "https://github.com/nikeandocean/carbon-factor-matcher#readme",
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "git+https://github.com/nikeandocean/carbon-factor-matcher.git"
40
+ },
41
+ "bugs": {
42
+ "url": "https://github.com/nikeandocean/carbon-factor-matcher/issues"
43
+ },
36
44
  "dependencies": {},
37
45
  "engines": {
38
46
  "node": ">=18.0.0"