claude-code-tools

TypeScript toolkit for Claude Code — code review, auto-fix, tests, lint, and format exposed as an MCP server and a small CLI.

What is this?

claude-code-tools is a TypeScript package that implements common developer workflows so Claude (via Model Context Protocol) or your own scripts can:

• Review files or diffs for risky patterns (e.g. eval, debugger, possible secrets, TODOs) plus optional custom rules
• Auto-fix with ESLint --fix, Prettier, and safe line-based cleanups (standalone console.log / console.debug / console.info, up to maxFixesPerFile), with an approval gate by default
• Run tests via your configured command (default npm test)
• Generate test skeletons for Vitest or Jest
• Lint and format with the ESLint and Prettier APIs
• Suggest refactors using lightweight heuristics (line length, nesting, etc.)

All processing runs locally on your machine.

Requirements

• Node.js 20+ (22+ recommended for tooling parity)
• Optional: Claude Code or any MCP-capable client

Installation

cd claude-code-tools
npm install
npm run build

The dist/ output is gitignored. Run npm run build before using node dist/..., npm run review, npm run fix, or registering dist/index.js in your MCP client.

npm scripts

Script	Description
npm run build	Compile src/ → dist/
npm run dev	Run MCP server on stdio from TypeScript (stdio; blocks)
npm run lint	ESLint on src/ and tests/
npm test	Vitest (unit + integration)
npm run test:integration	Integration smoke tests
npm run review	node dist/cli.js review (after build)
npm run test-run	node dist/cli.js test-run
npm run fix	node dist/cli.js fix
npm run test:watch	Vitest in watch mode
npm run prepack	Runs before npm pack / publish (npm run build)

Quick start

1. MCP server (stdio)

Build, then register the server (absolute path required):

{
  "mcpServers": {
    "dev-tools": {
      "command": "node",
      "args": ["/absolute/path/to/claude-code-tools/dist/index.js"]
    }
  }
}

Restart the client. Registered tools:

Tool	Purpose
code_review	Review a file or diff
auto_fix	ESLint/Prettier + safe console-line removals
test_runner	Run the test command
test_writer	Emit a test skeleton (write optional: save next to source)
lint	ESLint
format	Prettier
refactor_suggest	Heuristic suggestions

Development (TypeScript, stdio):

npm run dev

2. CLI

After npm run build:

# Review a file (JSON output)
node dist/cli.js review --file src/index.ts

# Only errors and warnings (drop info-level findings)
node dist/cli.js review --file src/index.ts --severity-warn-only

# Pipe a diff
git diff | node dist/cli.js review --diff -

# Run tests (uses `.claude-tools.config.json` when present)
node dist/cli.js test-run

# Auto-fix: needs --auto-approve or CLAUDE_TOOLS_AUTO_APPROVE unless disabled in config
node dist/cli.js fix --file src/buggy.ts --auto-approve

Exit codes (fix): 0 success, 2 file not found, 3 approval required.

After npm link or publishing: claude-code-tools review --file ... (see package.json bin).

3. Programmatic API

import {
  reviewCode,
  autoFix,
  runTests,
  writeTests,
  runLint,
  runFormat,
  refactorSuggest,
} from 'claude-code-tools';

const review = await reviewCode({ path: './src/index.ts' });
console.log(review.summary, review.issues);

const fixed = await autoFix({ path: './src/buggy.ts', autoApprove: false });

const tests = await runTests({ command: 'npm test' });

const generated = await writeTests({
  path: './src/auth.ts',
  framework: 'vitest',
  write: false,
});
console.log(generated.generatedCode);

Use write: true to create a *.test.ts / *.spec.ts file next to the source (same as the MCP test_writer tool with write: true).

4. Custom rules

import { addCustomRule } from 'claude-code-tools/rules';

addCustomRule({
  name: 'no-console',
  description: 'Disallow console.log in production code',
  severity: 'warning',
  check: ({ source, filePath }) => {
    if (!/\.[jt]sx?$/.test(filePath)) {
      return [];
    }
    return source.includes('console.log')
      ? [
          {
            rule: 'no-console',
            message: 'Avoid console.log in production paths',
            severity: 'warning',
            suggestion: 'Use a logger',
          },
        ]
      : [];
  },
});

Configuration

Create .claude-tools.config.json in the project root:

{
  "review": {
    "ignorePatterns": ["**/*.test.ts", "dist/**"],
    "severityThreshold": "warning"
  },
  "autoFix": {
    "requireApproval": true,
    "maxFixesPerFile": 10
  },
  "testRunner": {
    "defaultCommand": "npm run test:ci",
    "timeoutMs": 60000
  },
  "lint": {
    "eslintConfig": "eslint.config.js"
  }
}

• severityThreshold: error | warning | info — caps which severities are reported after scanning.
• autoFix.requireApproval: when false, auto_fix applies ESLint/Prettier/console cleanups without the approval gate (default is true).
• maxFixesPerFile: max number of standalone console.* lines removed per auto-fix run (default 10).
• CLAUDE_TOOLS_AUTO_APPROVE: set to 1, true, or yes to allow destructive fixes without per-call autoApprove (see .env.example).

Docker

A Dockerfile is included. From the repo root:

docker build -t claude-code-tools .
docker run -i --rm -v "$(pwd)":/workspace -w /workspace claude-code-tools

Testing

npm run lint
npm test
npm run test:integration

npm test runs the full Vitest suite, including tests/integration/. Use npm run test:integration if you only want the smoke tests.

Project layout

claude-code-tools/
├── src/
│   ├── tools/           # code-review, auto-fix, test-runner, …
│   ├── mcp-server.ts    # MCP tool registration
│   ├── cli.ts           # CLI entry (also package bin)
│   ├── rules.ts         # Custom rules registry (export: claude-code-tools/rules)
│   ├── config.ts
│   └── index.ts         # Library API; MCP stdio when executed as main
├── tests/
├── Dockerfile
├── .dockerignore
├── .env.example
├── .gitignore
├── eslint.config.js
├── LICENSE
├── README.md
├── package.json
├── package-lock.json
├── tsconfig.json
└── vitest.config.ts

License

This project is licensed under the MIT License.

Acknowledgements

Built with TypeScript, @modelcontextprotocol/sdk, ESLint, and Prettier.