Content
# Tool List
> AI-powered code generation protection tool based on MCP protocol — syntax validation, duplicate detection, multi-agent coordination.
[](https://www.npmjs.com/package/lintpulse-mcp)
[](LICENSE)
[](https://nodejs.org)
## Features
- **Syntax Validation** — Single-pass state machine, detects bracket/quote matching, multi-line strings, and unterminated symbols, supporting 7 languages
- **Duplicate Detection** — Project-level symbol extraction (name + type deduplication), Levenshtein similarity (long name truncation optimization), and 10K file scan limit
- **Multi-Agent Coordination** — Symbol ownership declaration, conflict detection, `complete_agent` completion marker, mutex + state persistence
- **Pattern Detection** — Detects `as any`, `console.log`, `TODO`, `unwrap()` and other anti-patterns
- **Line Ending Management** — LF/CRLF detection, conversion, and project-level normalization (automatically skips binary files)
- **MCP Resources** — Exposes project state, symbol table, and agent list as subscribable resources
- **Concurrency Safety** — Promise-chain mutex, global write queue (failure auto-recovery), and cross-instance state synchronization
## Quick Start
### Requirements
- Node.js >= 18.0.0
- npm >= 9.0.0
### Installation
```bash
npm install -g lintpulse-mcp
```
### MCP Configuration
Run the initialization command to automatically register with common MCP clients:
```bash
npx lintpulse-mcp init
```
Default registration targets: Claude Code, Claude Desktop, Codex. Available options:
```bash
npx lintpulse-mcp init --target claude-code
npx lintpulse-mcp init --target claude-desktop,codex
npx lintpulse-mcp init --dry-run
npx lintpulse-mcp init --force
```
## MCP Tool List
| Tool Name | Function | Priority |
| --- | --- | --- |
| `validate_syntax` | Checks bracket/quote matching | P0 |
| `check_duplicates` | Checks for symbol duplicates | P0 |
| `scan_project_symbols` | Scans project symbols | P0 |
| `analyze_code` | Comprehensive analysis of syntax, patterns, and duplicates | P0 |
| `detect_line_endings` | Detects line ending types (LF/CRLF/mixed) | P0 |
| `convert_line_endings` | Converts single file line ending format | P0 |
| `normalize_line_endings` | Batch normalizes project line endings | P0 |
| `register_agent` | Registers agent instance | P1 |
| `claim_symbol` | Declares symbol ownership | P1 |
| `release_symbol` | Releases symbol ownership | P1 |
| `check_before_write` | Conflict check before writing | P1 |
| `get_project_state` | Gets project state | P1 |
| `cleanup_agent` | Cleans up agent resources | P1 |
| `complete_agent` | Marks agent completion, symbol converted to implemented | P1 |
| `batch_validate` | Batch validates multiple file syntax | P1 |
| `smart_check` | Intelligently selects check items | P2 |
| `quick_analyze` | Quick analysis returns simplified results | P2 |
## MCP Resources
| URI | Name | Description |
| --- | --- | --- |
| `lintpulse://project/{path}/state` | Project State | Agent count, symbol count, active agent overview |
| `lintpulse://project/{path}/symbols` | Symbol Table | Project complete symbol list and location |
| `lintpulse://project/{path}/agents` | Agent List | All agent tasks, status, declared symbols |
**Supported Languages**: TypeScript, JavaScript, Python, Rust, Go, Java, C++, C#, Ruby, PHP, Swift, Kotlin
**Keyword Filtering**: Each language has a built-in 40~60 keyword blacklist to avoid misidentifying `if`, `for`, `return`, etc. as function names. Scanning automatically skips `dist`/`build`/`target`/`__pycache__`/`.git` and other build directories.
## Project Structure
```
src/
├── index.ts # Entry file
├── server.ts # MCP Server wiring (stdio, tool/resource registration, public method delegation)
├── types.ts # Type definitions + symbol extraction regex
├── cli/
│ └── init.ts # init subcommand: registers Claude/Codex MCP configuration
├── core/
│ └── symbol-cache.ts # LRU symbol cache + scan cache helper
├── tools/
│ ├── schemas.ts # Zod schema single source
│ ├── registry.ts # Tool table + Zod → JSON Schema derivation
│ └── handlers.ts # 17 tool handlers
├── resources/
│ └── registry.ts # MCP Resource templates + read dispatch
├── validators/
│ ├── syntax.ts # Syntax validator (stack + state machine + O(log n) line/column positioning)
│ ├── duplicate.ts # Duplicate detector (symbol extraction + Levenshtein + project scan)
│ ├── patterns.ts # Pattern detector (as any / console.log / TODO, etc.)
│ └── line-endings.ts # Line ending detection, conversion, project-level normalization
├── coordination/
│ ├── agent-manager.ts # Agent management (mutex + state cache refresh)
│ └── state-store.ts # JSON state persistence (atomic write + backup rotation + global write queue)
└── utils/
├── errors.ts # CodeGuardError error class
├── logger.ts # Graded logging (debug/info/warn/error)
├── code-position.ts # Line/column calculation tool (pre-computation + binary search)
└── path-safety.ts # projectPath + filePath out-of-bounds check
tests/
├── unit/ # Unit tests (8 files)
├── integration/ # MCP integration tests
└── stress/ # High-concurrency stress tests
```
## Development
```bash
git clone https://github.com/DarkInno/LintPulse-MCP.git
cd LintPulse-MCP
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run 105 tests
npm run typecheck # TypeScript type check
npm run lint # ESLint check
npm run format # Prettier formatting
```
### Available Commands
| Command | Description |
| --- | --- |
| `npm run build` | Compile `src/` → `dist/` |
| `npm run typecheck` | `tsc --noEmit` type check |
| `npm test` | Vitest runs all unit tests |
| `npm run test:watch` | Vitest watch mode |
| `npm run test:coverage` | Run tests and generate coverage report |
| `npm run lint` | ESLint check `src/` and `tests/` |
| `npm run lint:fix` | ESLint auto-fix |
| `npm run format` | Prettier formatting |
| `npm start` | Start MCP Server (`node dist/index.js`) |
| `npx lintpulse-mcp init` | Auto-register to Claude Code / Claude Desktop / Codex |
### Performance Metrics
| Metric | Target |
| --- | --- |
| Syntax validation response | < 100ms (1000 lines) |
| Project scan time | < 5s (1000 files) |
| Memory usage | < 200MB |
| Concurrent agents | 10+ |
## License
[MIT License](LICENSE)
