Skip to main content
Glama
README.md
# mcp-kritisi

A [Model Context Protocol](https://modelcontextprotocol.io) stdio server that exposes the `kritisi` Solidity security toolkit to MCP-compatible clients. It provides security audits with designed PDF reports, NatSpec documentation, import merging, and provider configuration inspection.

`mcp-kritisi` is a thin wrapper around the published `kritisi` package. Provider access, report parsing, PDF generation, and file-safety rules all come from that library; this project only adds the MCP transport and tool schemas.

## Features

- `security_audit` returns high/medium/low findings and can write a designed PDF report.
- `natspec_document` generates NatSpec comments and never writes files unless asked.
- `merge_imports` flattens a Solidity file and its imports with `sol-merger`.
- `show_config` reports effective provider settings with API keys redacted.
- Supports OpenRouter (default), OpenAI, Claude/Anthropic, and DeepSeek.
- Works over stdio with any MCP client, including Claude Desktop and Qoder.
- Refuses non-`.sol` inputs and protects existing files unless `overwrite` is set.
- API keys are read from environment variables or the user's kritisi config, never from tool arguments.

## Requirements

- Node.js 18 or newer.
- An API key for the provider you intend to use.

## Install

### From npm

Install the server globally:

```bash
npm install --global mcp-kritisi
mcp-kritisi --help
```

Or run it on demand without a global install:

```bash
npx -y mcp-kritisi --help
```

### From source

```bash
git clone https://github.com/zororaka00/mcp-kritisi.git
cd mcp-kritisi
npm ci
npm run build
node dist/index.js --version
```

The build output is written to `dist/`. The package depends on `kritisi` from npm.

## Client configuration

Add the server to your MCP client configuration. The example below uses `npx` so no global install is required:

```json
{
  "mcpServers": {
    "kritisi": {
      "command": "npx",
      "args": ["-y", "mcp-kritisi"],
      "env": {
        "OPENROUTER_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

Optional provider settings can be added to `env`, for example `OPENROUTER_MODEL`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`.

If the package is installed globally, use `"command": "mcp-kritisi"` with no arguments. When running from a source checkout, use `"command": "node"` and the absolute path to `dist/index.js` in `args`.

## Programmatic usage

The package root also exposes a side-effect-free library entrypoint for embedding the tools in another MCP server:

```js
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
const { registerKritisiTools, version } = require('mcp-kritisi');

const server = new McpServer({ name: 'my-server', version });
registerKritisiTools(server);
```

`registerKritisiTools` adds the four tools to an existing server; `version` is the installed package version. Importing the package does not start a server or open stdio.

## Configuration

Environment variables take precedence over the user-local kritisi config at `~/.config/kritisi/config.json` (or `$XDG_CONFIG_HOME/kritisi/config.json`). Set `KRITISI_CONFIG_PATH` to use a different file.

| Variable | Purpose | Default |
| --- | --- | --- |
| `OPENROUTER_API_KEY` | OpenRouter API key | none |
| `OPENROUTER_MODEL` | OpenRouter model | `openai/gpt-5.6-sol` |
| `OPENROUTER_BASE_URL` | OpenRouter endpoint override | `https://openrouter.ai/api/v1/chat/completions` |
| `OPENAI_API_KEY` | OpenAI API key | none |
| `OPENAI_MODEL` | OpenAI model | `gpt-5.6-sol` |
| `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY` | Claude API key | none |
| `ANTHROPIC_MODEL` / `CLAUDE_MODEL` | Claude model | `claude-opus-5` |
| `DEEPSEEK_API_KEY` | DeepSeek API key | none |
| `DEEPSEEK_MODEL` | DeepSeek model | `deepseek-v4-pro` |
| `KRITISI_TIMEOUT_MS` | Per-request timeout in milliseconds | `120000` |
| `KRITISI_RETRIES` | Retries for network errors and HTTP 429/5xx | `2` |
| `KRITISI_RETRY_DELAY_MS` | Base backoff delay; doubles per retry | `500` |
| `ANTHROPIC_MAX_TOKENS` / `CLAUDE_MAX_TOKENS` | Claude output token cap | `8192` |

Provider-specific `*_BASE_URL` variables are also supported. `show_config` displays the effective configuration and reports keys only as `set` or `unset`.

## Tools

All tools return JSON text content. Failures are returned as MCP tool errors (`isError: true`); the server stays running.

| Tool | Purpose | Writes files |
| --- | --- | --- |
| `security_audit` | Solidity security audit with optional PDF report | Only when `outputPdf` is set |
| `natspec_document` | Add NatSpec documentation | Only with `write: true` or `output` |
| `merge_imports` | Merge imports into one file | Only when `output` is set |
| `show_config` | Inspect effective provider configuration | Never |

### `security_audit`

| Input | Type | Default | Meaning |
| --- | --- | --- | --- |
| `path` | string | required | Path to a `.sol` file |
| `provider` | enum | `openrouter` | `openrouter`, `openai`, `claude`, `anthropic`, or `deepseek` |
| `outputPdf` | string | none | Write a PDF report to this path |
| `overwrite` | boolean | `false` | Replace an existing PDF |
| `includeReport` | boolean | `true` | Include the full findings JSON in the response |

Response: `provider`, `model`, `usage`, `summary` (`high`/`medium`/`low` counts), `pdf` (path or `null`), and `report` unless `includeReport` is false.

```json
{
  "path": "contracts/Vault.sol",
  "outputPdf": "reports/Vault.pdf"
}
```

Relative paths are resolved against the MCP server process working directory; prefer absolute paths in client configuration for predictable results.

### `natspec_document`

| Input | Type | Default | Meaning |
| --- | --- | --- | --- |
| `path` | string | required | Path to a `.sol` file |
| `provider` | enum | `openrouter` | AI provider |
| `write` | boolean | `false` | Update the source in place and keep a `.sol.bak` backup |
| `output` | string | none | Write the documented source to this path (implies writing) |
| `overwrite` | boolean | `false` | Replace an existing output file |

By default the documented source is returned and no file is touched. Markdown code fences are stripped, and responses that do not look like Solidity are rejected without modifying files.

### `merge_imports`

| Input | Type | Default | Meaning |
| --- | --- | --- | --- |
| `path` | string | required | Path to a `.sol` file |
| `output` | string | none | Write the merged source to this path |
| `overwrite` | boolean | `false` | Replace an existing output file |

Response: `source`, `written` (path or `null`), and `merged` (source text).

### `show_config`

Returns `configPath`, whether the config file exists, the installed `kritisi` `libraryVersion` and `libraryPath`, and the effective provider configuration with keys redacted.

## Safety

- Inputs must end in `.sol`; other paths are rejected before any provider request.
- Files are written only when a tool argument requests it. Existing outputs require `overwrite: true`.
- In-place NatSpec updates always create a `<file>.sol.bak` backup first.
- PDF reports include a cover page, risk badge, executive summary, finding blocks, paginated code panels, page numbers, provider/model metadata, and an AI-assistance disclaimer.
- API keys are never accepted as tool parameters. They are redacted from provider errors and reported only as `set`/`unset`.

## Development

```bash
npm ci
npm run lint
npm run format:check
npm test
npm audit
npm pack --dry-run
```

`npm test` builds the server and runs MCP protocol tests with the official SDK client and a local mock provider. The suite is network-free and covers tool discovery, configuration redaction, file guards, NatSpec backups, PDF creation, and error handling.

A live provider smoke test is not part of the automated suite. Run one only with credentials supplied intentionally through the environment.

## Publishing

`prepublishOnly` runs lint and tests. Before publishing:

```bash
npm run lint
npm test
npm pack --dry-run
npm publish --access public
```

Review the package contents with `npm pack --dry-run` and never commit API keys or local configuration files.

## Limitations

- Audit output is AI-assisted and not a substitute for a professional security review. Verify findings independently.
- Contract source is sent to the configured third-party provider.
- Model output is untrusted; instructions embedded in audited code can attempt prompt injection.
- Very large contracts may exceed the model context window. Split them before auditing.

## License

MIT; see [LICENSE](LICENSE).

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: showing configuration, security auditing, NatSpec documentation, and import merging. There is no meaningful overlap between tool behaviors or target outputs.

Naming Consistency4/5

All names use consistent snake_case with two-word identifiers, making the set easy to scan. The verb/noun convention is mostly predictable, though security_audit and natspec_document are more noun-oriented than the action-first names.

Tool Count5/5

Four tools is appropriately small for a focused Solidity utility wrapper. Each tool maps to a distinct workflow and none feels redundant or ornamental.

Completeness4/5

The surface covers configuration visibility, auditing, documentation generation, and import merging, which are the core operations implied by the server. Minor gaps exist around broader Solidity workflows, but the stated purpose is well served.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues