agentleFS
MarcusJellinghausMarcusJellinghaus/mcp-workspace/.claude/CLAUDE.md

mcp-workspace

CLAUDE.md49 starsChanged 2 days agoMITView on GitHub

mcp-workspace is an MCP server providing workspace file operations (read, write, edit, list, search) and read-only file access to reference projects (whose GitHub issues are writable — see below). Source code is in src/mcp_workspace/, tests in tests/. Python 3.11+ required. 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…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

14 rules. About 0 are common, 8 are distinctive, and 6 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.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 9
  2. Distinctive:

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

    line 14
  3. Distinctive:

    After making code changes, run:

    line 76
  4. Distinctive:

    All checks must pass before proceeding.

    line 84
  5. Very specific:

    Ruff: use mcp__mcp-tools-py__run_ruff_check.

    line 86
  6. Very specific:

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

    line 88
  7. Very specific:

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

    line 92
  8. Distinctive:

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

    line 96
  9. Very specific:

    Never use python -c via Bash.

    line 105
  10. Very specific:

    Status labels: use mcp__mcp-workspace__github_issue_set_status to change issue workflow status (works for reference projects too).

    line 123
  11. Very specific:

    Before every commit: run mcp__mcp-tools-py__run_format_code, then commit with mcp__mcp-workspace__git_commit.

    line 127
  12. Distinctive:

    Never create local workarounds — file issues/feature requests at mcp-coder-utils instead

    line 143
  13. Distinctive:

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

    line 149
  14. Distinctive:

    Never use the AskUserQuestion tool.

    line 157

≈ “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-workspace is an MCP server providing workspace file operations (read, write, edit, list, search) and read-only file access to reference projects (whose GitHub issues are writable — see below). Source code is in src/mcp_workspace/, tests in tests/. Python 3.11+ required.

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.

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
Delete directorymcp__mcp-workspace__delete_directory
Move filemcp__mcp-workspace__move_file
List directorymcp__mcp-workspace__list_directory
Search filesmcp__mcp-workspace__search_files
Search reference filesmcp__mcp-workspace__search_reference_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
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 (project's configured formatter)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 (read-only)mcp__mcp-workspace__git
Create / switch branchmcp__mcp-workspace__git_branch
Delete local branchmcp__mcp-workspace__git_branch_delete
Commitmcp__mcp-workspace__git_commit
Pushmcp__mcp-workspace__git_push
Force push after rebasemcp__mcp-workspace__git_push_force
Get base branchmcp__mcp-workspace__get_base_branch
Check file sizemcp__mcp-workspace__check_file_size
Check branch statusmcp__mcp-workspace__check_branch_status
List GitHub issuesmcp__mcp-workspace__github_issue_list
View GitHub issuemcp__mcp-workspace__github_issue_view
View GitHub PRmcp__mcp-workspace__github_pr_view
Search GitHubmcp__mcp-workspace__github_search
Create GitHub issuemcp__mcp-workspace__github_issue_create
Edit GitHub issuemcp__mcp-workspace__github_issue_edit
Set issue workflow statusmcp__mcp-workspace__github_issue_set_status
Comment on GitHub issuemcp__mcp-workspace__github_issue_comment
Reply to inline PR review commentmcp__mcp-workspace__github_review_comment_reply
Resolve inline PR review threadmcp__mcp-workspace__github_review_thread_resolve
Link a sub-issuemcp__mcp-workspace__github_subissue_add
List sub-issuesmcp__mcp-workspace__github_subissue_list
Unlink a sub-issuemcp__mcp-workspace__github_subissue_remove
Create GitHub PRmcp__mcp-workspace__github_pr_create
List GitHub labelsmcp__mcp-workspace__github_label_list

Sibling repos are readable in full via the reference tools, git with reference_name, and the GitHub read tools with reference_name (get_reference_projects lists them). Their issues are also writable with reference_name — create, edit and comment. 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.

Performance tests skip themselves under xdist. Run them as a second, serial pytest call: run_pytest_check(markers=["performance"], extra_args=["-n", "0"]).

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 gitignored; .mcp-file-access makes it read-write for the MCP file tools, and it is never committed.

Never use python -c via Bash. If you reason instead of running, label the conclusion analytical.

Git operations

Prefer MCP tools for read-only git operations: use mcp__mcp-workspace__git with the command parameter (log, diff, status, merge_base, show, branch, fetch, rev_parse, ls_tree, ls_files, ls_remote). These run without permission prompts.

Compact diff: mcp__mcp-workspace__git with command "diff" includes compact diff by default — detects moved code, collapses unchanged blocks. Use compact=False for raw output.

Allowed commands via Bash tool. These have no MCP equivalent — use Bash directly. Skills that instruct bash commands (e.g. git commit) must also use Bash.

git add / rebase (rebase conflict resolution: git add <file> + git rebase --continue)
gh issue comment --repo owner/repo (only for a repo that is not a configured reference project — otherwise use the MCP tool with reference_name)
gh issue view --repo owner/repo (only for a repo that is not a configured reference project — otherwise use the MCP tool with reference_name)
gh run view
mcp-coder gh-tool set-status <label>

Status labels: use mcp__mcp-workspace__github_issue_set_status to change issue workflow status (works for reference projects too). Skills that still call mcp-coder gh-tool set-status may keep using it. Never use raw gh issue edit with label flags.

Slash-prefixed gh arguments: prefix with MSYS_NO_PATHCONV=1 — Git Bash rewrites a leading / into a Windows path.

Before every commit: run mcp__mcp-tools-py__run_format_code, then commit with mcp__mcp-workspace__git_commit.

Bash discipline: no cd prefix. Don't chain approved with unapproved commands. Run them separately.

Commit messages: standard format. See Writing style for length. No attribution footers.

Shared Libraries

This project uses mcp-coder-utils (mcp-coder-utils reference project) for shared utilities:

ModuleImport
Loggingfrom mcp_coder_utils.log_utils import setup_logging, log_function_call

Rules:

  • Browse the source via mcp-coder-utils reference project before reimplementing anything
  • Never create local workarounds — file issues/feature requests at mcp-coder-utils instead

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.