codemap_project_help_replace

Find and replace text within an existing project help topic. Replaces the first occurrence by default; set `all: true` to replace every occurrence. Errors clearly if the topic doesn't exist or the search string isn't found.

project-helpdocumentationeditreplacetopics

Parameters

Name	Type	Required	Description
`topic`	`string`	✅ Required	Help topic name (e.g., "session-workflow")
`oldString`	`string`	✅ Required	Text to find. Must appear at least once in the topic content.
`newString`	`string`	✅ Required	Replacement text
`all`	`boolean`	❌ Optional	Replace all occurrences (default: false — replaces first occurrence only) (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

typescript

codemap_project_help_replace({
  topic: "session-workflow",
  oldString: "Run clean-build.bat before publishing",
  newString: "Run clean-build.bat and npm pack before publishing"
})

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "topic": "session-workflow",
    "replacements": 1,
    "all": false
  }
}

ℹ️When to Use This Tool

codemap_project_help_replace

Fix a typo or outdated command in a specific help topic without rewriting the whole file
Update a domain name, URL, version number, or config key across all mentions in a single topic (with all: true)
Make surgical edits to help topics as part of automated workflows (e.g. post-release scripts updating version strings)

💡Common Patterns

Version-bump pattern

codemap_project_help_replace "publishing-process" "v0.2.9" "v0.2.10" --all
codemap_project_help_replace "api-reference" "v0.2.9" "v0.2.10" --all

Chain a sweep across every topic that mentions the old version right after a release.

URL migration pattern

codemap_project_help_replace "deployment-guide" "staging.example.com" "staging.egentica.ai" --all
codemap_project_help_replace "env-variables" "API_URL=http://staging.example.com" "API_URL=http://staging.egentica.ai"

Split infrastructure moves across the relevant topics — keep oldString specific enough to avoid accidental matches.

💡Pro Tips

Default all: false is a safety net. It fails loudly if you expected a unique match but the old string appeared twice — stopping you from silently overwriting only one. Set all: true explicitly when you want sweep behavior.
STRING_NOT_FOUND is your idempotency signal. If a sweep has already run, the next call returns STRING_NOT_FOUND — not an error state, just "nothing left to do."
Keep oldString short and specific. Long oldStrings make failures hard to diagnose; short ones can collide with unrelated mentions. Aim for 5–15 words of uniquely identifying context.

✅Best Practices

Read the topic with codemap_project_help before replacing to confirm the text you're targeting still exists in the expected form
Prefer append over replace for adding NEW content — replace is for editing existing text, not extending it
When all: true, verify replacements in the response matches your expected count — catches bugs where oldString was more (or less) unique than you thought
Commit help topics like source code — a .codemap/project-help/ under version control gives you diff history for every replacement

⚠️Common Mistakes

❌ Mistake: Using replace to add a new section to a topic
✅ Instead: Use codemap_project_help_append — designed for adding, not editing

❌ Mistake: Passing oldString with trailing whitespace or stray newlines that don't match the file exactly
✅ Instead: Match exact whitespace — copy oldString directly from the topic's current content when unsure

❌ Mistake: Calling replace without all: true when the string appears multiple times, expecting all occurrences to update
✅ Instead: Set all: true explicitly — the default is first-occurrence-only on purpose

Changelog

1 release

- 🆕AddedNew tool added

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_project-help_append

codemap_project-help_read

codemap_project-help_add

codemap_project-help_edit