mcp-tools-py
CLAUDE.md21 starsChanged 3 months agoMITView on GitHub
mcp-tools-py is an MCP server exposing Python code-quality tools (pylint, pytest, mypy, ruff, black, isort, vulture, bandit, lint-imports) as structured MCP endpoints. This project depends on mcp-coder-utils for subprocess execution, logging, and file I/O. Import rule: never import mcp_coder_utils directly. Always use the local shim modules: This is enforced by the mcp_coder_utils_isolation contract in .importlinter. Do not reimplement functionality that exists in mcp-coder-utils. Check the mcp-coder-utils reference project before writing new utilities. Do NOT use native Claude Code file tools…
In this repository21 other files it gives its agents.
- check_branch_statusSkill
- commit_pushSkill
- discussSkill
- implementation_approveSkill
- implementation_finaliseSkill
- implementation_needs_reworkSkill
- implementation_new_tasksSkill
- implementation_reviewSkill
- implementation_review_supervisorSkill
- implement_directSkill
- issue_analyseSkill
- issue_analyse_supervisorSkill
- issue_approveSkill
- issue_createSkill
- issue_requirementsSkill
- issue_updateSkill
- plan_approveSkill
- plan_reviewSkill
- plan_review_supervisorSkill
- plan_updateSkill
- rebaseSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Import rule: never import mcp_coder_utils directly.
- Distinctive: line 25
Justify any native tool: Before Read, Write, Edit, Glob, Grep, or Bash, say in chat, on two lines:
- Distinctive: line 30
If you can't name the gap, use the MCP tool.
- Distinctive: line 75
After making code changes, run:
- Distinctive: line 83
All checks must pass before proceeding.
- Very specific: line 85
Ruff: use mcp__mcp-tools-py__run_ruff_check.
- Very specific: line 87
Pytest: always use extra_args: ["-n", "auto"] for parallel execution.
- Very specific: line 102
When debugging test failures, add "-v", "-s", "--tb=short" to extra_args.
- Distinctive: line 106
Don't assert Python behaviour you haven't run.
- Distinctive: line 128
Bash-only (no MCP equivalent): Use Bash directly. Skills that instruct bash commands (e.g.
- Very specific: line 140
Before every commit: run mcp__mcp-tools-py__run_format_code, then stage and commit.
- Distinctive: line 154
Don't restate investigation the tool calls already show (file reads, searches, test runs).
- Distinctive: line 162
Never use the AskUserQuestion tool.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
About this repo
mcp-tools-py is an MCP server exposing Python code-quality tools (pylint, pytest, mypy, ruff, black, isort, vulture, bandit, lint-imports) as structured MCP endpoints.
Shared libraries
This project depends on mcp-coder-utils for subprocess execution, logging, and file I/O.
Import rule: never import mcp_coder_utils directly. Always use the local shim modules:
| Need | Import from |
Logging (log_function_call, setup_logging, OUTPUT) | mcp_tools_py.log_utils |
Subprocess (execute_command, CommandResult, etc.) | mcp_tools_py.utils.subprocess_runner |
File I/O (read_file) | mcp_tools_py.utils.file_utils |
This is enforced by the mcp_coder_utils_isolation contract in .importlinter.
Do not reimplement functionality that exists in mcp-coder-utils. Check the mcp-coder-utils reference project before writing new utilities.
MCP Tools — mandatory
Do NOT use native Claude Code file tools (Read, Write, Edit, Glob, Grep, Bash) for any operation that has an MCP equivalent. Always use the mcp__mcp-workspace__* tools instead. This applies to all file reading, writing, editing, searching, listing, and git operations. If no MCP equivalent exists, use Bash. Check the tool mapping table below first.
Justify any native tool. Before Read, Write, Edit, Glob, Grep, or Bash, say in chat, on two lines:
- What it does — one sentence.
- Why MCP doesn't — which tool you'd have used, and what stops it.
If you can't name the gap, use the MCP tool. Exempt: the approved git/gh commands under Git operations.
No session scratchpad. MCP tools can't write outside the project. Temporary files go in .scratch/.
Tool mapping
| Task | MCP tool |
| Read file | mcp__mcp-workspace__read_file |
| Edit file | mcp__mcp-workspace__edit_file |
| Write file | mcp__mcp-workspace__save_file |
| Append to file | mcp__mcp-workspace__append_file |
| Delete file | mcp__mcp-workspace__delete_this_file |
| Move file | mcp__mcp-workspace__move_file |
| List directory | mcp__mcp-workspace__list_directory |
| Search files | mcp__mcp-workspace__search_files |
| Read reference project | mcp__mcp-workspace__read_reference_file |
| List reference dir | mcp__mcp-workspace__list_reference_directory |
| Get reference projects | mcp__mcp-workspace__get_reference_projects |
| Search reference files | mcp__mcp-workspace__search_reference_files |
| Check file size | mcp__mcp-workspace__check_file_size |
| Check branch status | mcp__mcp-workspace__check_branch_status |
| Get base branch | mcp__mcp-workspace__get_base_branch |
| Run pytest | mcp__mcp-tools-py__run_pytest_check |
| Run pylint | mcp__mcp-tools-py__run_pylint_check |
| Run mypy | mcp__mcp-tools-py__run_mypy_check |
| Run vulture | mcp__mcp-tools-py__run_vulture_check |
| Run lint-imports | mcp__mcp-tools-py__run_lint_imports_check |
| Run ruff check | mcp__mcp-tools-py__run_ruff_check |
| Run ruff fix | mcp__mcp-tools-py__run_ruff_fix |
| Run bandit | mcp__mcp-tools-py__run_bandit_check |
| Format code (black+isort) | mcp__mcp-tools-py__run_format_code |
| Check a Python semantic before claiming it | scratch probe — see Scratch probes |
| Get library source | mcp__mcp-tools-py__get_library_source |
| Refactoring | mcp__mcp-tools-py__move_symbol, move_module, rename_symbol, list_symbols, find_references |
| Git (status, log, diff, fetch, etc.) | mcp__mcp-workspace__git |
gh issue view | mcp__mcp-workspace__github_issue_view |
gh issue list | mcp__mcp-workspace__github_issue_list |
gh pr view | mcp__mcp-workspace__github_pr_view |
gh search | mcp__mcp-workspace__github_search |
Sibling repos are readable in full via the reference tools and git with reference_name (get_reference_projects lists them). Check there before asking about another repo.
Code quality checks
After making code changes, run:
mcp__mcp-tools-py__run_pylint_check
mcp__mcp-tools-py__run_pytest_check
mcp__mcp-tools-py__run_mypy_checkAll checks must pass before proceeding.
Ruff: use mcp__mcp-tools-py__run_ruff_check. Do not call ruff directly.
Pytest: always use extra_args: ["-n", "auto"] for parallel execution.
Available marker: integration (requires external resources).
# Fast unit tests (recommended for regular development)
mcp__mcp-tools-py__run_pytest_check(extra_args=["-n", "auto", "-m", "not integration"])
# All tests (slow)
mcp__mcp-tools-py__run_pytest_check(extra_args=["-n", "auto"])
# Integration tests only
mcp__mcp-tools-py__run_pytest_check(extra_args=["-n", "auto"], markers=["integration"])When debugging test failures, add "-v", "-s", "--tb=short" to extra_args.
Scratch probes
Don't assert Python behaviour you haven't run. Probe it:
mcp__mcp-workspace__save_file(".scratch/test_probe.py", ...)
mcp__mcp-tools-py__run_pytest_check(extra_args=["-p", "no:cacheprovider", ".scratch/test_probe.py"])A path argument scopes the run, so a probe costs seconds. Delete when done — delete_directory(".scratch", recursive=True); CI blocks any PR carrying one. .scratch/ is not gitignored: the MCP file tools refuse ignored paths.
Git operations
MCP tools (use these for read-only git and GitHub queries):
mcp__mcp-workspace__git (status, log, diff, fetch, show, merge_base, ls_files, ls_remote, etc.)
mcp__mcp-workspace__github_issue_view
mcp__mcp-workspace__github_issue_list
mcp__mcp-workspace__github_pr_view
mcp__mcp-workspace__github_search
mcp__mcp-workspace__check_branch_statusBash-only (no MCP equivalent). Use Bash directly. Skills that instruct bash commands (e.g. git commit) must also use Bash.
git commit / add / push / push --force-with-lease / checkout / checkout -b / branch
git rebase / rm / restore / stash / remote get-url
gh issue create / edit / comment (labels only via gh-tool set-status)
gh issue view (cross-repo only — otherwise use the MCP tool)
gh run view
mcp-coder gh-tool set-status <label>
mcp-coder check file-size --max-lines 750Before every commit: run mcp__mcp-tools-py__run_format_code, then stage and commit.
Bash discipline: no cd prefix, no git -C. Don't chain approved with unapproved commands. Run them separately.
Slash-prefixed gh arguments: prefix with MSYS_NO_PATHCONV=1 — Git Bash rewrites a leading / into a Windows path. Without it --body "/approve" posts a path, the Action never fires, and the issue silently fails to transition.
Commit messages: standard format. See Writing style for length. No attribution footers.
Pull requests: no "Generated with Claude Code" footer. Keep descriptions concise.
Writing style
Before sending, cut any sentence that doesn't tell the reader something new or change what they do next — chat, commits, PRs, docs, comments, skill output alike. No pleasantries, no hedging, no filler opens or closes; hedge only when the uncertainty changes the action. Stay readable: short clauses or arrow chains over dense paragraphs; lead with the outcome.
Don't restate investigation the tool calls already show (file reads, searches, test runs). In chat, give the conclusion and the decision points only — not a narrated walkthrough of how you got there.
Progress during loops
Repeating the same action across 3+ items (e.g. files, issues, repos) → one short line per item as it completes, not just a final summary.
Asking questions
Never use the AskUserQuestion tool. Ask questions as plain text in the chat.
Obsidian knowledge base
Shared knowledge base across my repos (obsidian-dev-wiki), via the obsidian-wiki MCP server.
Read at the start of non-trivial work: Home.md (index), the Repos/<current repo>.md note, and any Processes/ note matching the task. If a process note covers the task, follow it rather than improvising.
Write only what passes all three tests:
- durable — still true in 6 months (not status, versions, or task state)
- general — applies beyond the one issue that produced it
- homeless — no better place already exists
Existing homes, check before writing: code and docstrings; the repo's docs/; CLAUDE.md for how-I-work rules; the GitHub issue for a single defect's root cause; git history for what changed when.
Always write to Field Notes/, for Marcus to promote. Only edit Repos/, Processes/, or Plans/ when Marcus explicitly asks for it. If an existing note already covers the topic, name it in the Field Note (Promote into [[Note Name]]) instead of editing that note. Follow Conventions.md for frontmatter and naming.
MCP server issues
Alert immediately if MCP tools are not accessible — this blocks all work.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

