mcp-purity

Imported from pontscho/prompt-heaven (ClaudeCode/skills/mcp-purity/SKILL.md). Install upstream with npx skills add pontscho/prompt-heaven --skill mcp-purity. Copyright stays with the author.

Overview

MCP-Purity is a file operations and code-intelligence MCP server. It exposes a single tool purity_call that dispatches file handler functions via the function parameter. MCP tool name: mcp__mcp-purity__purity_call

Quick Start

{"f":"","p":{}}

Returns server status and list of available functions.

Available Functions

1. read_file — Read a file

{"f":"read_file","p":{"relative_path":"src/main.py","start_line":1,"end_line":50}}

2. create_text_file — Create or overwrite a file

Creates parent directories automatically. Destructive — overwrites existing files.

{"f":"create_text_file","p":{"relative_path":"src/utils.py","content":"def add(a, b):\n    return a + b\n"}}

3. list_dir — List directory contents

{"f":"list_dir","p":{"relative_path":"src","recursive":true,"skip_ignored_files":true}}
{"f":"list_dir","p":{"relative_path":".claude/tmp","filter":"p80-s1*"}}

4. find_file — Find files by wildcard pattern

{"f":"find_file","p":{"file_mask":"*.test.ts","relative_path":"src"}}

5. replace_content — Replace content in a file

Regex mode uses standard Python re.sub() backreferences: \1, \2, \g<name>.

{"f":"replace_content","p":{"relative_path":"config.py","needle":"DEBUG = True","repl":"DEBUG = False","mode":"literal"}}

6. delete_lines — Delete a range of lines

{"f":"delete_lines","p":{"relative_path":"src/app.py","start_line":10,"end_line":15}}

7. replace_lines — Replace a range of lines

{"f":"replace_lines","p":{"relative_path":"src/app.py","start_line":5,"end_line":7,"content":"    return new_value\n"}}

8. insert_at_line — Insert content at a line

Existing content at line shifts down. Does not replace.

{"f":"insert_at_line","p":{"relative_path":"src/main.py","line":1,"content":"# Auto-generated\n"}}

9. search_for_pattern — Regex search across files

{"f":"search_for_pattern","p":{"substring_pattern":"TODO|FIXME","context_lines_after":1,"paths_include_glob":"**/*.py"}}

regex and line_numbers are accepted as ripgrep-compatibility no-ops: substring_pattern is always a regex and content rows always carry path:line:, so passing them true changes nothing. Passing false is a hard error — purity has no literal-match mode, and silently regex-matching a pattern meant literally is the failure that would follow. For rows without line numbers use output_mode: "files_with_matches" or "count".

The gitignore filter never hides .claude/tmp. The scratch area is gitignored on purpose but is exactly where the fleet's working files land, so a search that skipped it would hide the artifacts a minion wrote seconds earlier. Applies to search_for_pattern and list_dir alike; find_file never ignore-filters at all. The exemption is narrow: if .claude itself is gitignored, only .claude/tmp comes back — the rest of the ignored subtree stays ignored.

Parameter aliases

All handlers accept the aliases below as a convenience — callers can use the shorter / more familiar form and the server folds them onto the canonical names from the tables above before the handler runs. The canonical name is what error messages reference.

Global aliases (apply to every function)

Function-specific aliases (override globals for the named function)

Function-name aliases

Unknown-parameter hint

When a handler raises an error (e.g. a missing required parameter), the error message is augmented with a list of any caller-supplied keys that are not known to the canonical function. Example:

Missing required parameter: needle | Unknown params for 'replace_content': foo_bar. Accepted: allow_multiple_occurrences, mode, needle, relative_path, repl.

Use the hint to spot typos or wrong-alias choices in the next call.

Error Handling

All errors return {"error":"message"} in the tool response with isError: true. Common errors:

• Missing required parameters
• Path escapes project root (sandbox violation)
• File/directory not found
• Invalid regex pattern
• Multiple occurrences when allow_multiple_occurrences is false

Security

All paths are sandboxed under --project-root. Symlinks are resolved before validation. Attempts to escape the project root via .. or absolute paths are rejected.

Semantic / Symbol Navigation (clangd-backed)

Beyond file operations, purity_call also exposes compiler-accurate symbol navigation for C/C++/CUDA, backed by an embedded clangd LSP (folded in from the former mcp-clangd / mcp-cuda servers). Prefer these over grep for any C/C++/CUDA symbol question. The standalone clangd_call / cuda_call tools are no longer registered and do not exist — purity_call is the only entry point.

The backend spins up lazily on the first semantic call (clangd init + indexing can take tens of seconds the first time; subsequent calls are fast). For CUDA projects it auto-discovers the CUDA SDK and sm_xx arch. Paths are confined under --project-root like every other purity function; lines/characters are 1-based.

Semantic functions

{"f":"find_definition","p":{"symbol":"my_function"}}
{"f":"find_references","p":{"relative_path":"src/main.c","line":42,"character":10}}
{"f":"outline","p":{"relative_path":"src/main.c"}}
{"f":"type_at","p":{"relative_path":"src/main.cpp","line":20,"character":8}}

find_definition / find_references route automatically: pass a symbol name for name-based lookup, or relative_path+line+character for position-based lookup. Prefer symbol_context over separate def+refs, and symbol_change_impact before refactoring.

find_type_definition is position-only (no by-name spelling) and hops one level at a time: from a variable or a call result it lands on the typedef name, and from that name it lands on the underlying struct/enum tag — so reaching a tag from a variable takes two calls. It returns an explicit error, never a grep guess, when the position has no resolvable type.

Migration from clangd_call / cuda_call

The legacy function names still work through purity_call (registered as direct aliases), so existing calls keep functioning. Canonical mapping:

The _at variants fold onto their non-_at counterpart (position vs name is auto-detected from the params). Param aliases folded in from clangd: symbol→symbol_name, col/column/char→character, max/count→max_results, depth→call_hierarchy_depth. The path key is relative_path (purity's canonical), with path/file/file_path accepted as aliases.