Repository avatar
Security
v1.0.1
active

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_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:

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.

VariablePurposeDefault
OPENROUTER_API_KEYOpenRouter API keynone
OPENROUTER_MODELOpenRouter modelopenai/gpt-5.6-sol
OPENROUTER_BASE_URLOpenRouter endpoint overridehttps://openrouter.ai/api/v1/chat/completions
OPENAI_API_KEYOpenAI API keynone
OPENAI_MODELOpenAI modelgpt-5.6-sol
ANTHROPIC_API_KEY / CLAUDE_API_KEYClaude API keynone
ANTHROPIC_MODEL / CLAUDE_MODELClaude modelclaude-opus-5
DEEPSEEK_API_KEYDeepSeek API keynone
DEEPSEEK_MODELDeepSeek modeldeepseek-v4-pro
KRITISI_TIMEOUT_MSPer-request timeout in milliseconds120000
KRITISI_RETRIESRetries for network errors and HTTP 429/5xx2
KRITISI_RETRY_DELAY_MSBase backoff delay; doubles per retry500
ANTHROPIC_MAX_TOKENS / CLAUDE_MAX_TOKENSClaude output token cap8192

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.

ToolPurposeWrites files
security_auditSolidity security audit with optional PDF reportOnly when outputPdf is set
natspec_documentAdd NatSpec documentationOnly with write: true or output
merge_importsMerge imports into one fileOnly when output is set
show_configInspect effective provider configurationNever

security_audit

InputTypeDefaultMeaning
pathstringrequiredPath to a .sol file
providerenumopenrouteropenrouter, openai, claude, anthropic, or deepseek
outputPdfstringnoneWrite a PDF report to this path
overwritebooleanfalseReplace an existing PDF
includeReportbooleantrueInclude 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

InputTypeDefaultMeaning
pathstringrequiredPath to a .sol file
providerenumopenrouterAI provider
writebooleanfalseUpdate the source in place and keep a .sol.bak backup
outputstringnoneWrite the documented source to this path (implies writing)
overwritebooleanfalseReplace 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

InputTypeDefaultMeaning
pathstringrequiredPath to a .sol file
outputstringnoneWrite the merged source to this path
overwritebooleanfalseReplace 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

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.

NPM
mcp-kritisi
Install Command
npm install mcp-kritisi