# 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**.

[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-MCP-3178C6)](https://docs.anthropic.com/claude-code)
[![MCP](https://img.shields.io/badge/MCP-1.x-FF6B6B)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-20+-green)](https://nodejs.org/)

## 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

```bash
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):

```json
{
  "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):**

```bash
npm run dev
```

### 2. CLI

After `npm run build`:

```bash
# 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

```typescript
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

```typescript
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:

```json
{
  "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:

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

## Testing

```bash
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](LICENSE).

## Acknowledgements

Built with [TypeScript](https://www.typescriptlang.org/), [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk), [ESLint](https://eslint.org/), and [Prettier](https://prettier.io/).