agentleFS
MarcusJellinghausMarcusJellinghaus/mcp-tools-py/.claude/CLAUDE.md

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…

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
  1. Very specific:

    Import rule: never import mcp_coder_utils directly.

    line 9
  2. Distinctive:

    Justify any native tool: Before Read, Write, Edit, Glob, Grep, or Bash, say in chat, on two lines:

    line 25
  3. Distinctive:

    If you can't name the gap, use the MCP tool.

    line 30
  4. Distinctive:

    After making code changes, run:

    line 75
  5. Distinctive:

    All checks must pass before proceeding.

    line 83
  6. Very specific:

    Ruff: use mcp__mcp-tools-py__run_ruff_check.

    line 85
  7. Very specific:

    Pytest: always use extra_args: ["-n", "auto"] for parallel execution.

    line 87
  8. Very specific:

    When debugging test failures, add "-v", "-s", "--tb=short" to extra_args.

    line 102
  9. Distinctive:

    Don't assert Python behaviour you haven't run.

    line 106
  10. Distinctive:

    Bash-only (no MCP equivalent): Use Bash directly. Skills that instruct bash commands (e.g.

    line 128
  11. Very specific:

    Before every commit: run mcp__mcp-tools-py__run_format_code, then stage and commit.

    line 140
  12. Distinctive:

    Don't restate investigation the tool calls already show (file reads, searches, test runs).

    line 154
  13. Distinctive:

    Never use the AskUserQuestion tool.

    line 162

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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:

NeedImport 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

TaskMCP tool
Read filemcp__mcp-workspace__read_file
Edit filemcp__mcp-workspace__edit_file
Write filemcp__mcp-workspace__save_file
Append to filemcp__mcp-workspace__append_file
Delete filemcp__mcp-workspace__delete_this_file
Move filemcp__mcp-workspace__move_file
List directorymcp__mcp-workspace__list_directory
Search filesmcp__mcp-workspace__search_files
Read reference projectmcp__mcp-workspace__read_reference_file
List reference dirmcp__mcp-workspace__list_reference_directory
Get reference projectsmcp__mcp-workspace__get_reference_projects
Search reference filesmcp__mcp-workspace__search_reference_files
Check file sizemcp__mcp-workspace__check_file_size
Check branch statusmcp__mcp-workspace__check_branch_status
Get base branchmcp__mcp-workspace__get_base_branch
Run pytestmcp__mcp-tools-py__run_pytest_check
Run pylintmcp__mcp-tools-py__run_pylint_check
Run mypymcp__mcp-tools-py__run_mypy_check
Run vulturemcp__mcp-tools-py__run_vulture_check
Run lint-importsmcp__mcp-tools-py__run_lint_imports_check
Run ruff checkmcp__mcp-tools-py__run_ruff_check
Run ruff fixmcp__mcp-tools-py__run_ruff_fix
Run banditmcp__mcp-tools-py__run_bandit_check
Format code (black+isort)mcp__mcp-tools-py__run_format_code
Check a Python semantic before claiming itscratch probe — see Scratch probes
Get library sourcemcp__mcp-tools-py__get_library_source
Refactoringmcp__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 viewmcp__mcp-workspace__github_issue_view
gh issue listmcp__mcp-workspace__github_issue_list
gh pr viewmcp__mcp-workspace__github_pr_view
gh searchmcp__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_check

All 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_status

Bash-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 750

Before 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.