npm package: @sankalpsthakur/carbon
Description: Open-source Claude Code SDK for end-to-end Scope 1/2/3 decarbonisation workflows
Latest version: 0.2.0

# Carbon

AI agent for end-to-end Scope 1/2/3 carbon accounting and decarbonisation workflows.

11 plugins, 6 MCP servers (105 tools), 74 slash commands, 52 agents, 118 skills.

Built on the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) — type `carbon` to get an interactive AI agent with all 6 MCP servers as tools, or use it as a bundle of Claude Code plugins and MCP servers.

## Quick Start

```bash
# Install from npm
npm i -g @sankalpsthakur/carbon

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Launch interactive agent
carbon

# Resume a previous session
carbon chat <session-id>

# Or use utility commands
carbon list
carbon validate scope3-calculation
carbon help
```

### From source

```bash
git clone <repo-url> carbon && cd carbon

# Install dependencies
cd plugins && npm install

# Launch interactive agent
ANTHROPIC_API_KEY=sk-ant-... node shared-services/tools/carbon-cli.js

# Run smoke tests (6 MCP servers, 105 tools)
node test-mcp-servers.js

# Run all unit tests (253 tests)
node --test **/__tests__/*.test.js

# Validate all plugin manifests
node shared-services/tools/validate.js
```

## Project Structure

```
carbon/
  plugins/
    scope3-calculation/    # Scope 3 calc engine (13 MCP tools)
    scope3-execution/      # Pipeline orchestration, OCR provenance (23 tools)
    scope3-strategy/       # CSRD/DMA materiality, risk scanning (20 tools)
    scope12-accounting/    # Scope 1/2 accounting, KPI, reporting (23 tools)
    swarms/                # DAG-based multi-agent orchestration (16 tools)
    connectors/            # ERP/CRM/expense schema mapping (10 tools)
    shared-services/       # Store adapter, CLI, cross-plugin infra
    ai-engineering/        # Model training, inference, RAG workflows
    growth-content/        # Campaign planning, content batching
    quality-monitoring/    # Quality gates, visual testing
    sales-outreach/        # Revenue execution, voice qualification
  docker/                  # Dockerfiles for all MCP servers
  docs/                    # Architecture docs, swarm guides
  Makefile                 # Docker, test, backup targets
```

## MCP Servers

All 6 servers speak JSON-RPC 2.0 over stdio (default) or HTTP.

| Server | Tools | Port (HTTP) | Health Endpoint |
|--------|-------|-------------|-----------------|
| calc | 13 | 8401 | `calc.health` |
| exec | 23 | 8402 | `exec.health` |
| strategy | 20 | 8403 | `strategy.health` |
| scope12 | 23 | 8404 | `scope12.health` |
| swarm | 16 | 8405 | `swarm.health` |
| connectors | 10 | 8406 | `connectors.health` |

## CLI

```bash
# Install from npm (recommended)
npm i -g @sankalpsthakur/carbon

# Launch interactive agent (requires ANTHROPIC_API_KEY)
carbon

# Resume a previous session
carbon chat <session-id>

# Or use utility commands
carbon <command>
```

Commands:

| Command | Description |
|---------|-------------|
| `carbon` | Launch interactive AI agent (6 MCP servers, 105 tools) |
| `carbon chat [session-id]` | Launch agent, optionally resume a session |
| `carbon list` | List all 11 installed plugins |
| `carbon init <name>` | Scaffold a new plugin |
| `carbon run <plugin>:<tool>` | Spawn MCP server and call a tool |
| `carbon validate <plugin>` | Check plugin.json, commands, MCP health |
| `carbon export <plugin>:<job_id>` | Create audit bundle with hashes |
| `carbon help` | Show usage |

### Interactive Agent Commands

Inside the interactive agent, these commands are available:

| Command | Description |
|---------|-------------|
| `/status` | Show MCP server connection status |
| `/session` | Show current session ID (for resume) |
| `/cost` | Show accumulated cost and turns |
| `/help` | Show available commands |
| `/exit` | Exit the agent |

## Testing

```bash
cd plugins

# Smoke tests — starts each MCP server, sends initialize + tools/list + health
node test-mcp-servers.js

# All 253 unit tests
node --test **/__tests__/*.test.js

# Individual suites
npm run test:store       # Store adapter (file/SQLite backends)
npm run test:calc        # Scope 3 calculation engine
npm run test:exec        # Execution pipeline
npm run test:strategy    # Strategy & DMA tools
npm run test:scope12     # Scope 1/2 accounting
npm run test:swarm       # Swarm orchestration
npm run test:connectors  # Schema-mapping connectors
```

## Docker

```bash
# SQLite (default)
make up

# With Ollama LLM backend
make up-ollama

# Stop
make down

# Logs
make logs
```

Services run on ports 8401-8406. See `docs/HTTP_QUICK_START.md` for HTTP API usage.

## Store Backends

Data persistence uses a pluggable store adapter (`shared-services/tools/store-adapter.js`):

| Backend | Config | Use Case |
|---------|--------|----------|
| File (JSON) | Default | Development, single-user |
| SQLite | `CARBONKIT_DB_BACKEND=sqlite` | Production single-node |

Postgres is planned but not yet supported. All backends implement `get`, `set`, `list`, `delete`, `bulkSet`, `count`.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CARBONKIT_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
| `CARBONKIT_MCP_PORT` | per-server | HTTP port when transport=http |
| `CARBONKIT_DB_BACKEND` | `file` | Store backend: `file` or `sqlite` |
| `CARBONKIT_AUTH_SECRET` | (none) | JWT secret for HTTP auth (required for production) |
| `CARBONKIT_CORS_ORIGIN` | `*` | CORS origin for HTTP mode (set explicitly in production) |
| `CARBONKIT_MAX_UPLOAD_BYTES` | `10485760` | Max upload size for REST gateway (10MB) |
| `CARBONKIT_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |

## Security Notes

- **Auth**: When `CARBONKIT_AUTH_SECRET` is unset, all HTTP endpoints are unauthenticated (open mode). Always set it for non-localhost deployments.
- **CORS**: Defaults to `*`. Set `CARBONKIT_CORS_ORIGIN` to your domain in production.
- **CLI trust boundary**: `carbon run` executes commands from plugin `.mcp.json` files. Only install plugins you trust — a malicious plugin.json can run arbitrary code.

## License

Apache-2.0