
mcp-kritisi
io.github.zororaka00/mcp-kritisi
MCP server for Solidity security audits, NatSpec documentation, and import merging.
Documentation
mcp-kritisi
A Model Context Protocol 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_auditreturns high/medium/low findings and can write a designed PDF report.natspec_documentgenerates NatSpec comments and never writes files unless asked.merge_importsflattens a Solidity file and its imports withsol-merger.show_configreports 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-
.solinputs and protects existing files unlessoverwriteis 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:
npm install --global mcp-kritisi
mcp-kritisi --help
Or run it on demand without a global install:
npx -y mcp-kritisi --help
From source
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:
{
"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:
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.
{
"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.bakbackup 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
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:
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.
Publishing to the MCP Registry
This repository is prepared for the official MCP Registry under the name io.github.zororaka00/mcp-kritisi. The registry entry is described by server.json, and the mcpName field in package.json must match the name in that file.
Publish the npm package first, then use the official mcp-publisher CLI installed from its releases or Homebrew (do not install it from npm):
mcp-publisher validate
mcp-publisher login github
mcp-publisher publish
The registry is currently in preview, so metadata or API behavior may change. See the official publishing quickstart for platform-specific installation commands and current requirements. Keep package.json, server.json, and the npm version aligned when releasing updates.
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.
mcp-kritisinpm install mcp-kritisi