Server data from the Official MCP Registry
Scan any codebase, generate CONVENTIONS.md, expose conventions as MCP tools for AI agents.
Scan any codebase, generate CONVENTIONS.md, expose conventions as MCP tools for AI agents.
patchwork is a well-designed code analysis tool with appropriate permissions for its purpose. The MCP server implementation includes proper input validation (path containment checks, blocked system directories), no credential exposure, and safe error handling. Minor code quality concerns around broad exception handling and input validation edge cases do not substantially impact security. Supply chain analysis found 4 known vulnerabilities in dependencies (0 critical, 4 high severity). Package verification found 1 issue (1 critical, 0 high severity).
5 files analyzed · 10 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Unverified package source
We couldn't verify that the installable package matches the reviewed source code. Proceed with caution.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-sainarayana-b-patchwork": {
"args": [
"patchwork-conventions"
],
"command": "uvx"
}
}
}From the project's GitHub README.
Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.
Every team that uses AI coding assistants hits the same wall: Claude writes getUserById in a codebase that uses get_user_by_id. Cursor creates components/userCard.tsx in a project that uses user-card.tsx. The agent invented a response shape that doesn't match the rest of the API.
You write a CLAUDE.md manually. It goes stale in two weeks. You write it again.
patchwork automates this. It scans your actual source code using AST analysis and detects what your team really does — not what you think you do.
| Category | What's mined |
|---|---|
| Naming | Functions, classes, variables, constants, files — with confidence score and real examples |
| Imports | Absolute vs relative, path aliases (@/, src/), barrel files, destructuring style |
| Structure | Source root, test layout, feature vs layer organisation, monorepo detection |
| Error Handling | try/except vs Result types, logging framework, custom exception naming, propagation style |
| Testing | Framework, assertion style, mocking library, coverage tool, fixture patterns |
| API Patterns | Response shape, route param style, ORM, async pattern, GraphQL/gRPC presence |
| Git Workflow | Commit message style, branch naming, co-change file pairs |
| Tech Stack | Frameworks, package manager, linters, formatters, type checker, build tool, scripts |
pip install patchwork-conventions
cd your-project
patchwork scan
That's it. You'll get a CONVENTIONS.md like this:
# CONVENTIONS.md
> Auto-generated by patchwork on 2026-06-25
## Tech Stack
**Language:** python
**Runtime:** Python >=3.11
**Package Manager:** uv
**Frameworks:** fastapi, sqlalchemy
**Linters:** ruff
**Formatters:** ruff, black
## Naming Conventions
### Python
- **Functions:** `snake_case` (97% consistent)
- Examples: `get_user`, `parse_response`, `create_session`
- **Classes:** `PascalCase` (100% consistent)
- Examples: `UserService`, `AuthHandler`, `DatabaseClient`
- **Constants:** `SCREAMING_SNAKE`
- Examples: `MAX_RETRIES`, `API_BASE_URL`
- **Files:** `snake_case`
- **Private prefix:** `_`
- **Test functions:** prefix `test_`
## Project Structure
**Source root:** `src/`
**Organisation:** layer-based
**Tests:** separate (`tests/`)
**Key directories:**
- `src/` — source root
- `tests/` — test suite
- `migrations/` — database migrations
## Error Handling
### Python
- **Pattern:** try/except
- **Propagation:** raise
- **Logging:** `structlog`
- **Custom exception naming:** Error suffix
- `ValidationError`, `AuthError`, `NotFoundError`
## Testing Conventions
### Python
- **Framework:** pytest
- **Coverage:** 34 test files / 89 source files (38% ratio)
- **Assertions:** `assert(...)`
- **Coverage tool:** `pytest-cov`
- **Patterns:** fixtures, factories
## Git Conventions
- **Commit style:** conventional commits
- **Examples:** `feat(auth): add JWT refresh`, `fix(api): handle null user`
- **Branch naming:** feature/name + fix/name
| Feature | patchwork | argus | sourcebook |
|---|---|---|---|
| AST-based naming analysis | ✅ tree-sitter | ❌ filesystem only | ❌ not done |
| Confidence scores | ✅ per-category | ❌ | ❌ |
| Real examples from your code | ✅ | ❌ | ❌ |
| Counter-examples (inconsistencies) | ✅ | ❌ | ❌ |
| Error handling pattern mining | ✅ | ❌ | ❌ |
| API response shape detection | ✅ | ❌ | ❌ |
| Co-change file pairs | ✅ | ❌ | ✅ |
Convention checking (check cmd) | ✅ | ❌ | ❌ |
| MCP server with 8 tools | ✅ | ❌ | ✅ (4 tools) |
| Watch mode | ✅ | ✅ (sync) | ✅ |
| Zero LLM required | ✅ | ✅ | ✅ (layer A) |
| Open source / MIT | ✅ | ✅ | ❌ BSL |
# Generate CONVENTIONS.md
patchwork scan
# Generate for a specific path
patchwork scan /path/to/project
# Generate AGENTS.md
patchwork scan --agents-md
# Append to CLAUDE.md
patchwork scan --claude-md
# Output JSON (for programmatic use)
patchwork scan --json
# Print to stdout (don't write file)
patchwork scan --stdout
# Limit to specific languages
patchwork scan --lang python --lang typescript
# Re-scan and update, preserving manual edits
patchwork update
# Show what would change
patchwork diff
# Print detected conventions to terminal
patchwork show
# Auto-watch mode (regenerate on change)
patchwork watch
# Start MCP server
patchwork serve --stdio # for Claude Code
patchwork serve --port 3742 # HTTP mode
patchwork scan # run once
# CONVENTIONS.md is automatically read by Claude Code
patchwork scan --claude-md
Claude Code — add to ~/.claude.json (or run claude mcp add interactively):
{
"mcpServers": {
"patchwork": {
"command": "patchwork",
"args": ["serve", "/path/to/your/project", "--stdio"]
}
}
}
Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"patchwork": {
"command": "patchwork",
"args": ["serve", "/path/to/your/project", "--stdio"]
}
}
}
Cursor — add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"patchwork": {
"command": "patchwork",
"args": ["serve", ".", "--stdio"]
}
}
}
Then your AI agent can use 8 on-demand tools:
| Tool | When to use |
|---|---|
patchwork_scan | Get complete conventions overview |
patchwork_naming | Before writing new identifiers |
patchwork_structure | Before creating new files/directories |
patchwork_stack | When choosing libraries or commands |
patchwork_errors | Before writing error handling |
patchwork_testing | Before writing test files |
patchwork_git | Before writing commit messages |
patchwork_check | Validate a proposed name |
Copy SKILL.md from this repo to ~/.claude/skills/patchwork/SKILL.md to get /patchwork slash commands.
# Keep CONVENTIONS.md updated as you code
patchwork watch &
# Or in CI — fail if conventions changed
patchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m "chore: update conventions")
from patchwork import scan
from patchwork.scanner import ScanOptions
from pathlib import Path
# Full scan
report = scan(ScanOptions(root=Path(".")))
# Render to markdown
print(report.to_markdown())
# Render to JSON
import json
data = json.loads(report.to_json())
# Access specific results
naming = report.naming.get("python")
print(f"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})")
print(f"Examples: {naming.functions.examples}")
structure = report.structure
print(f"Source root: {structure.source_root}")
print(f"Organisation: {structure.organisation}")
| Language | AST (tree-sitter) | Fallback regex |
|---|---|---|
| Python | ✅ full | ✅ |
| TypeScript | ✅ full | ✅ |
| JavaScript | ✅ full | ✅ |
| Go | ✅ (with full extra) | ✅ |
| Rust | ✅ (with full extra) | ✅ |
| Java | ✅ (with full extra) | ✅ |
| Ruby, PHP, C#, C++ | ❌ | ✅ regex only |
Install full language support:
pip install 'patchwork-conventions[full]'
your codebase
│
▼
ConfigDetector ← reads package.json, pyproject.toml, go.mod, Cargo.toml
│
▼
File discovery ← respects .gitignore, skips node_modules etc.
│
▼
Per-language AST ← tree-sitter parses every file into a syntax tree
│
├── NamingMiner → extracts function/class/variable names, classifies style
├── ImportMiner → detects import patterns, aliases, barrel files
├── StructureMiner → analyses directory layout, test co-location
├── ErrorHandlingMiner → detects try/catch patterns, logging, custom exceptions
├── TestingMiner → identifies framework, assertion style, mocking
├── APIPatternMiner → finds response shapes, ORMs, route styles
└── GitPatternMiner → mines commit history, branches, co-change pairs
│
▼
ConventionReport
│
├── CONVENTIONS.md (default)
├── AGENTS.md (--agents-md)
├── CLAUDE.md (--claude-md, appends)
└── JSON (--json)
All analysis is 100% local — no API calls, no telemetry, no data leaves your machine.
On a 1,000-file TypeScript monorepo:
On a 500-file Python project:
Results are deterministic — same codebase always produces the same output.
git clone https://github.com/yourusername/patchwork
cd patchwork
pip install -e '.[dev]'
pytest
Pull requests welcome. See CONTRIBUTING.md.
MIT — free for personal and commercial use.
claude-code · agent-skills · mcp · context-engineering · hallucination-detection · code-conventions · static-analysis · tree-sitter · developer-tools · ai-coding
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.