Metadata-Version: 2.4
Name: canforge-mcp
Version: 0.1.0
Summary: Local, read-only MCP tools for CAN databases and capture logs
Project-URL: Homepage, https://canforge.io/canforge-mcp
Project-URL: Repository, https://github.com/canforge/canforge-mcp
Project-URL: Changelog, https://github.com/canforge/canforge-mcp/blob/main/CHANGELOG.md
Author-email: André Delgado <andre@adelgado.io>
License: MIT License
        
        Copyright (c) 2026 André Delgado
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: CAN,DBC,MCP,automotive,canbus
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: capkit<0.3,>=0.2
Requires-Dist: dbckit<2,>=1.0
Requires-Dist: mcp<2,>=1.28
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# canforge-mcp

[![PyPI](https://img.shields.io/pypi/v/canforge-mcp)](https://pypi.org/project/canforge-mcp/)
[![CI](https://github.com/canforge/canforge-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/canforge/canforge-mcp/actions/workflows/ci.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/canforge-mcp)](https://pypi.org/project/canforge-mcp/)
[![License: MIT](https://img.shields.io/pypi/l/canforge-mcp)](LICENSE)

`canforge-mcp` is a local, read-only MCP server for inspecting DBC files and
decoding CAN capture logs.

Files stay on the machine running the server. The server exposes bounded tools
instead of uploading captures or returning unbounded traces.

## Tools

| Tool | Purpose |
|---|---|
| `dbc_info` | DBC version, message/signal/node counts, and node names |
| `list_messages` | Bounded message summaries, with optional search |
| `get_message` | Full message and signal detail by name or arbitration ID |
| `search_signals` | Bounded signal search across a DBC |
| `decode_frame` | Decode one hexadecimal CAN payload |
| `validate_dbc` | Structured DBC validation issues |
| `diff_dbcs` | Added, removed, and changed messages and signals |
| `probe_log` | Detect a log format and read header metadata |
| `log_stats` | Frame count, span, ID counts, and median cycle times |
| `read_frames` | Bounded raw-frame samples with ID and time filters |
| `decode_log` | Bounded decoded frames from a DBC and log |
| `signal_timeseries` | Downsampled timestamp/value points for one signal |

See [the tool reference](docs/tools.md) for arguments, return shapes, and hard
caps.

## Install

Run directly with `uvx`:

```bash
uvx canforge-mcp
```

Or install with pip:

```bash
pip install canforge-mcp
canforge-mcp
```

Requires Python `>=3.11`.

## Configure

Claude Code:

```bash
claude mcp add canforge -- uvx canforge-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "canforge": {
      "command": "uvx",
      "args": ["canforge-mcp"]
    }
  }
}
```

Restart the client after changing its MCP configuration.

## Design

- Local-first: tools accept filesystem paths and do not send file content over
  the network.
- Read-only: no tool creates, edits, encodes, or overwrites a file.
- Bounded: list and frame tools enforce hard caps and report `total`,
  `returned`, and `truncated`; timeseries are downsampled server-side.
- Cached: parsed DBCs are cached by resolved path and nanosecond modification
  time for repeated inspection during one server session.
- Composable: [capkit](https://github.com/canforge/capkit) reads capture formats;
  [dbckit](https://github.com/canforge/dbckit) parses and decodes DBC content.
- Stdio-only: version 0.1 exposes no network transport or hosted service.

## Scope and Caveats

- Supported capture formats come from capkit 0.2: Kvaser CanKing TXT, candump
  text, and Vector ASC.
- DBC support and validation behavior follow dbckit 1.x.
- Timestamps are floats exactly as recorded by capkit; they are not rebased.
- Median cycle time is the median gap between consecutive occurrences of an ID.
- `signal_timeseries` uses deterministic, evenly spaced index sampling when a
  series exceeds `max_points`; it is intended for inspection, not resampling or
  signal processing.
- Paths are resolved by the machine running the MCP server. A remote client's
  filesystem is not visible to a server running elsewhere.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
mypy canforge_mcp
pytest --cov=canforge_mcp --cov-fail-under=90
python -m build
```

## License

MIT
