codemap_project_help_append
Append text to the end of an existing project help topic. A separator is inserted between the existing content and the new text (default: two newlines). Trims trailing whitespace from existing content to prevent blank-line accumulation. Errors if the topic doesn't exist.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
topic | string | ✅ Required | Help topic name (e.g., "publishing-process") |
text | string | ✅ Required | Text to append to the end of the topic |
separator | string | ❌ Optional | Separator between existing and new content (default: two newlines) (default: \n\n) |
Usage Examples
MCP Usage (for AI Agents like Claude)
typescript
codemap_project_help_append({
topic: "publishing-process",
text: "## Post-Publish Checklist\n- Verify `npm view @egentica/codemap version` shows new version\n- Update NEXT_SESSION.md\n- Tag the release commit in git"
})Example Output
JSON Response
json
{
"success": true,
"data": {
"topic": "publishing-process",
"appended": true,
"newSize": 2847
}
}When to Use This Tool
-
Use
- Add new content to the end of an existing help topic without rewriting the whole file
- Accumulate release notes, checklists, or contact lists over time with consistent formatting
- Drive automated documentation updates from CI/CD pipelines (e.g. appending each release's notes to an archive topic)
- Grow a topic incrementally across many sessions without worrying about trailing-whitespace drift
codemap_project_help_append when you need to:
Common Patterns
Append-to-archive pattern
Each call tacks one more section onto a living document. The auto-trim prevents blank lines from accumulating across many appends.
Idempotent append pattern
Safe to run on every CI build — re-runs after a partial pipeline failure don't duplicate entries.
Bullet-list growth pattern
Single-newline separator keeps list items flush together instead of introducing blank-line gaps.
codemap_project_help_append "changelog-archive" "### v0.2.10 ..."
codemap_project_help_append "changelog-archive" "### v0.2.11 ..."
codemap_project_help_append "changelog-archive" "### v0.2.12 ..."Each call tacks one more section onto a living document. The auto-trim prevents blank lines from accumulating across many appends.
Idempotent append pattern
codemap_project_help → read current content
if new entry already present → skip
else → codemap_project_help_append Safe to run on every CI build — re-runs after a partial pipeline failure don't duplicate entries.
Bullet-list growth pattern
codemap_project_help_append "team-contacts" "- New member" --separator "\n"Single-newline separator keeps list items flush together instead of introducing blank-line gaps.
Pro Tips
- The default separator is
\n\n, which works perfectly for new markdown sections (headings, paragraphs). Override only when you need flush-joined content like list items. - Trailing whitespace is auto-trimmed from existing content before appending, so you won't end up with three blank lines when the existing file already ends with one. Safe to call repeatedly.
newSizein the response is post-append total size in bytes — useful for tracking growth or flagging when a topic is getting too large and should be split.
Best Practices
- Prefer
appendoverreplacefor growing content; usereplaceonly for editing existing text in place - Before CI-automated appends, guard with an idempotency check: read the topic and scan for the entry you're about to add
- When appending user-supplied content, sanitize it first —
textis inserted verbatim and markdown can clash with the topic's existing structure - Keep a dedicated
changelog-archivetopic for accumulating release notes so your main topics stay lean
Common Mistakes
❌ Mistake: Using
✅ Instead: Use
❌ Mistake: Manually including leading newlines in
✅ Instead: Let the
❌ Mistake: Calling
✅ Instead: Either read the topic first and skip already-present entries, or design the calling script so partial re-runs are impossible
append to update an existing paragraph mid-file✅ Instead: Use
codemap_project_help_replace — append always adds to the end, never edits existing text❌ Mistake: Manually including leading newlines in
text to create spacing✅ Instead: Let the
separator parameter handle spacing. Leading newlines in text stack with the separator and create unintended blank lines.❌ Mistake: Calling
append in a loop without idempotency checks, then re-running after a partial failure✅ Instead: Either read the topic first and skip already-present entries, or design the calling script so partial re-runs are impossible
Changelog
1 release- 🆕AddedNew tool added