add-mcp-tool
Skill125 starsChanged 7 months agoMITView on GitHub
Use when adding a new `Memory*` tool to remindb's MCP server — symptoms include "expose X over MCP", "register a new tool with the SDK", "add an endpoint to pkg/mcp/tools/", "wire a new MemoryXxx into registerTools", or any task that gives MCP clients a new capability backed by the store/engine/tracker.
12 other projects use a version of this.
Adopted by
Most recently taken up by
- janusson/MSMCPtheir own version, first seen Oct 25, 2026
- skillist-io/skillisttheir own version, first seen Oct 11, 2026
- james5101/jobtracktheir own version, first seen Oct 11, 2026
- Locker-Room-Tools/synapsetheir own version, first seen Oct 11, 2026
- letehaha/moneymattertheir own version, first seen Oct 11, 2026
- openfootmanager/openfootmanagertheir own version, first seen Oct 8, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- openfootmanager/openfootmanager★ 1.2ksame name
- letehaha/moneymatter★ 243same name
- dylanroscover/Embody★ 219same name
- tacticlaunch/mcp-linear★ 151same name
- paulieb89/property-shared★ 16same name
- plumbkit/plumb★ 4same name
- james5101/jobtrack★ 2same name
- Locker-Room-Tools/synapse★ 2same name
- janusson/MSMCP★ 1same name
- skillist-io/skillist★ 1same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-bench-scenarioSkill
- add-fuzz-targetSkill
- add-integration-testSkill
- add-parserSkill
- add-store-querySkill
- tune-temperature-policySkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 11 edited versions we read keep these.
2
Distinctive
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
- Very specific: line 78
Read tools also call d.boostResultNodes(ctx, result) to bump temperature on accessed nodes — mutating tools do not (the write itself is the …
- Very specific: line 91
Keep the name Memory<Verb> so it sorts cleanly with the existing inventory and matches the defer d.logCall(...) argument.
- Very specific: line 123
Update the frontmatter description tool list.
- Distinctive: line 124
Update the opening / inventory paragraph to reflect the new surface.
- Distinctive: line 125
Add at least one example call into the relevant pattern section.
- Very specific: line 144
Read tool that mutates: If your tool mutates (even just bumping temperature), it must take OpMu.
- Very specific: line 147
Passing the raw payload as a log attr: Use byte-count ("payload_bytes", len(input.Payload)) — payloads can be MB, and slog will serialize …
“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a new MCP tool
Tools live in pkg/mcp/tools/ as one file per tool. Each tool is a method on *Deps that takes a typed input struct, calls into Store / Engine / Tracker, and returns a *mcp.CallToolResult with text content. Adding one means four changes plus a docs sync.
Where it lands
| File | What changes |
pkg/mcp/tools/<tool>.go | New file — XxxInput struct + HandleXxx method on *Deps |
pkg/mcp/server.go | Add a mcp.AddTool(srv, ...) entry to registerTools |
pkg/mcp/tools/tools_test.go | Test using mcptest.NewEnv from internal/mcptest |
skills/remind/SKILL.md (read tools) or skills/memorize/SKILL.md (write tools) | Add the new tool to the inventory and any pattern section it belongs in |
Tool file template
The shape is uniform across fetch.go, search.go, summarize.go, write.go. Mirror it.
package tools
import (
"context"
"fmt"
"time"
gomcp "github.com/modelcontextprotocol/go-sdk/mcp"
)
type ExampleInput struct {
Anchor string `json:"anchor" jsonschema:"Node ID to operate on"`
Budget int `json:"budget,omitempty" jsonschema:"Token budget for the response"`
}
func (d *Deps) HandleExample(ctx context.Context, _ *gomcp.CallToolRequest, input ExampleInput) (_ *gomcp.CallToolResult, _ any, err error) {
defer d.logCall("MemoryExample", &err, time.Now(), "anchor", input.Anchor, "budget", input.Budget)
// Write-side tools take the lock; read-side tools do not (see "Locking" below).
// d.Store.OpMu.Lock()
// defer d.Store.OpMu.Unlock()
result, err := d.Engine.DoSomething(ctx, input.Anchor, input.Budget)
if err != nil {
return nil, nil, fmt.Errorf("failed to do-something: %w", err)
}
d.boostResultNodes(ctx, result) // read tools only
return &gomcp.CallToolResult{
Content: []gomcp.Content{&gomcp.TextContent{Text: result.Format()}},
}, nil, nil
}Five things every tool gets right:
- Named return values for the deferred logger.
(_ *gomcp.CallToolResult, _ any, err error)is the SDK signature; theerrname is required sodefer d.logCall(..., &err, ...)can capture the final error. Renaming or omittingerrsilently breaks call logging. defer d.logCall(...)on the first line. Prefix the tool name withMemoryto match the registered name. Pass enough attrs to debug a misbehaving call (anchor, budget, payload byte-count — never the full payload).- Locking decision (see below).
- Error wrapping. Action errors take
failed to <verb>:pergo-concise.md§5; wrap the engine/store error with%wso callers canerrors.Is. - Return
*mcp.CallToolResultwith text content. Format complex results into one string before returning — clients render text, not structured JSON.
Locking
The store uses a single sync.Mutex exposed as Store.OpMu (memory: "no wrapper methods around sync primitives"). The rule:
| Tool kind | Take OpMu |
Read-only (MemorySearch, MemoryFetch, MemoryTree, MemoryDelta, MemoryHistory, MemoryRelated) | No |
Mutating (MemoryWrite, MemorySummarize, MemoryCompile, MemoryRelate) | Yes |
Mutating tools call d.Store.OpMu.Lock() immediately after the deferred logger and defer d.Store.OpMu.Unlock(). See pkg/mcp/tools/summarize.go:21-22 and write.go:24-25 for the canonical pattern.
Read tools also call d.boostResultNodes(ctx, result) to bump temperature on accessed nodes — mutating tools do not (the write itself is the access).
The registration entry
Open pkg/mcp/server.go:146-186 (the registerTools function) and add:
mcp.AddTool(srv, &mcp.Tool{
Name: "MemoryExample",
Description: "<one short sentence — what it does, not how>",
}, d.HandleExample)Keep the name Memory<Verb> so it sorts cleanly with the existing inventory and matches the defer d.logCall(...) argument.
The test
pkg/mcp/tools/tools_test.go uses the in-process MCP transport via internal/mcptest.NewEnv(t). Call your tool through the client session and assert on the text output:
func TestExample_HappyPath(t *testing.T) {
env := mcptest.NewEnv(t)
res := env.CallTool(t, "MemoryExample", map[string]any{
"anchor": "<seeded-id>",
"budget": 500,
})
text := env.TextContent(t, res)
if !strings.Contains(text, "<expected substring>") {
t.Fatalf("unexpected output: %s", text)
}
}The docs sync — easy to skip, easy to regret
Two public skills under skills/ are the contract with future Claude sessions about what tools exist. Pick the one that matches the tool's side:
| Tool kind | Skill to update |
Read (MemoryTree, MemorySearch, MemoryFetch, MemoryDelta, MemoryHistory, MemoryRelated) | skills/remind/SKILL.md |
Write (MemoryWrite, MemorySummarize, MemoryCompile, MemoryRelate) | skills/memorize/SKILL.md |
| Crosses the boundary (introduces a new mental-model concept used on both sides) | Both |
For each affected skill, when you add a tool:
- Update the frontmatter
descriptiontool list. - Update the opening / inventory paragraph to reflect the new surface.
- Add at least one example call into the relevant pattern section.
Skipping this means future sessions won't know the tool exists. The skills are the API contract, not just docs.
Quick reference
1. pkg/mcp/tools/<tool>.go (Input struct + Handle method on *Deps)
2. pkg/mcp/server.go (mcp.AddTool entry in registerTools)
3. pkg/mcp/tools/tools_test.go (env := mcptest.NewEnv(t); env.CallTool(...))
4. skills/remind/SKILL.md (read tools)
OR
skills/memorize/SKILL.md (write tools)
OR both, when the change crosses the read/write boundary
5. go test ./pkg/mcp/... (must pass)Common mistakes
- Read tool that mutates. If your tool mutates (even just bumping temperature), it must take
OpMu. The temperature boost inboostResultNodesis the one exception — it goes throughTracker.RecordAccess→BoostTemperatureBatch, which serializes through SQLite's WAL writer, not the in-memory mutex. - Forgetting the named
errreturn.defer d.logCall(..., &err, ...)captureserrby pointer. If the function signature uses an unnamed error or shadowserrwith:=, the deferred log shows<nil>for failed calls. - Returning
nil, nil, nilon the no-result path. Return an empty*mcp.CallToolResultwith a text body like"no results"— clients expect text, not a missing content array. Seepkg/mcp/tools/search.goand thequery.FormatCompact"no results" string. - Passing the raw payload as a log attr. Use byte-count (
"payload_bytes", len(input.Payload)) — payloads can be MB, andslogwill serialize the whole thing. - Skipping the public-skill update. Tool exists in code but invisible to agents. Read tools must show up in
skills/remind/SKILL.md; write tools inskills/memorize/SKILL.md. Test: a fresh session reading the relevant skill should be able to use the new tool from the description alone.
Cross-references
.claude/rules/go-concise.md— error wrapping, naming, locking discipline, no-wrapper-methods rule.claude/rules/git-versioning.md— one commit per logical change; the four code edits ship together asfeat(mcp): add MemoryExample tool, the docs sync as a follow-updocs(skill): document MemoryExampleif it grew large, otherwise bundled.claude/skills/add-store-query/SKILL.md— if the new tool needs a query the store doesn't have yet, do that skill firstskills/remind/SKILL.md— docs target for read-side tools (MemoryTree,MemorySearch,MemoryFetch,MemoryDelta,MemoryHistory,MemoryRelated)skills/memorize/SKILL.md— docs target for write-side tools (MemoryWrite,MemorySummarize,MemoryCompile,MemoryRelate)
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
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.

