docs: MCP guide + agent-story refresh, correct stale content - #29
Conversation
Fills the narrative gaps the v0.19-v0.22 releases left (the reference is auto-generated; these are the hand-written pages). New / rewritten: - guides/mcp.mdx (new): the flagship `pdcli mcp serve` guide — read-only by default, the curated vs --allow-writes vs --topics/--all-tools tool model, the excluded surface, --tool-timeout, and claude-mcp-add / .mcp.json setup. Wired into a new "AI agents" sidebar group. - start/agents.mdx: adds an MCP section, exit rows 3 (lookup) and 8 (watch), lookup as the read-only create-vs-update branch, and the opt-in `deal context --mail` note. - Home.astro: the "Built for AI agents" card now leads with mcp serve; hero animation gains an `mcp serve` frame. Corrections: - guides/api.mdx: documents `api --paginate` (the old "does not auto-paginate" claim was false since v0.20), incl. the --jq shape shift. - start/distribution.mdx + automation/github-actions.mdx: version pins 0.20.0 -> 0.22.0. - concepts/api-model.mdx: `mail` added to the v1 topic row; `pdcli quota` introduced in the token-budget section (disambiguated from the sales "quota" metric). - guides/bulk.mdx: a `lookup ... && update || create` (exit 3) example. Claude-Session: https://claude.ai/code/session_018dRMUUj9vpKp3tqKQFsvE9
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ```bash | ||
| if pdcli lookup deal --field "PO Number" --value PO-1234 --first --jq .id >/tmp/id; then | ||
| pdcli deal update "$(cat /tmp/id)" --body '{"value":5000}' # found → update | ||
| else | ||
| pdcli deal create --body '{"title":"PO-1234","value":5000}' # exit 3 → create | ||
| fi | ||
| ``` | ||
|
|
||
| It resolves a human field name to its custom-field key for you (deal, person, org, product, | ||
| lead). Matching is **case-sensitive**, and — like upsert — the search index is eventually | ||
| consistent, so a `lookup`-then-`create` loop can still double-create in fast pipelines. |
There was a problem hiding this comment.
else silently swallows lookup errors as "not found"
The if/else branch treats every non-zero exit as "record missing, go create it." If pdcli lookup fails for any other reason — network outage (exit 69), rate-limit (exit 75), auth error (exit 77), etc. — the script falls straight into pdcli deal create, potentially creating a duplicate instead of surfacing the failure. The comment # exit 3 → create makes this look intentional but the guard is too broad. The same pattern appears in start/agents.mdx where pdcli lookup person … || pdcli person create … is described as a "clean create-if-missing pattern" — the || operator has the same flaw, running the create on any non-zero exit. Both examples should either check $? explicitly for exit 3 or call out that real callers should add that guard before using this pattern in production.
2 participants
Fills the narrative doc gaps from v0.19-v0.22 and fixes stale/incorrect pages (surfaced by a website audit).
New / rewritten
guides/mcp.mdx(new) — the flagshippdcli mcp serveguide (read-only by default, tool model, setup), in a new AI agents sidebar group.start/agents.mdx— MCP section, exit rows 3 (lookup) + 8 (watch), lookup create-vs-update, opt-in--mail.Home.astro— AI-agents card leads with MCP; hero gains anmcp serveframe.Corrections
guides/api.mdx: documentsapi --paginate(old "does not auto-paginate" was false since v0.20).0.20.0 → 0.22.0in distribution + github-actions.api-model.mdx:mailv1 row +pdcli quota(disambiguated from the sales-quota metric).bulk.mdx: alookupcreate-vs-update example.Astro build verified green locally (29 pages). Website is prettier/eslint-ignored.
https://claude.ai/code/session_018dRMUUj9vpKp3tqKQFsvE9
Greptile Summary
This PR fills documentation gaps introduced since v0.19 and corrects stale content surfaced by a site audit. The new
guides/mcp.mdxpage is the centrepiece, documenting thepdcli mcp serveserver — its read-only-by-default tool model, write gate, scope flags, field-name forcing, and timeout/limit guardrails — with a supporting "AI agents" sidebar group inastro.config.mjs.api.mdxnow documents--paginate/--all(the old "does not auto-paginate" note was wrong since v0.20);api-model.mdxaddsmailto the v1 topic table and documentspdcli quota; version pins indistribution.mdxandgithub-actions.mdxare bumped to 0.22.0.agents.mdxgains an MCP intro section, exit codes 3 and 8, the--mailopt-in fordeal context, and alookupcreate-if-missing example;bulk.mdxadds alookupcreate-vs-update shell pattern.Confidence Score: 4/5
Safe to merge after fixing the lookup shell examples — no runtime code changes, docs only.
The new and corrected documentation is accurate and well-structured throughout. The one concrete issue is that the lookup shell examples in bulk.mdx and agents.mdx both use an if/else or || pattern that treats every non-zero exit from pdcli lookup as record-not-found-go-create, but any error exit (network failure, auth problem, rate-limit) will also trigger the create branch, potentially producing duplicate records or masking the real failure. Users copy-pasting these examples into CI scripts would silently create records on transient errors.
website/src/content/docs/guides/bulk.mdx (lookup example, lines 231-241) and website/src/content/docs/start/agents.mdx (inline || pattern, lines 127-128) both demonstrate the same overly broad error-handling pattern.
Important Files Changed
mailto the v1 topic table and documentspdcli quotawith its--min/--thresholdflags and disambiguation from the sales "quota" metric.--paginate/--allflag including pager inference,--limitcap, and the--jqshape difference.lookupcreate-vs-update shell example, but theif/elsepattern catches all non-zero exits as "not found" rather than only exit 3, which can silently triggerdeal createon errors.--mailopt-in note, andlookupinline example; the `Sequence Diagram
%%{init: {'theme': 'neutral'}}%% sequenceDiagram participant Host as MCP Host participant MCP as pdcli mcp serve participant Child as pdcli child process participant PD as Pipedrive API Host->>MCP: list_tools MCP-->>Host: 45 read tools (default scope) Host->>MCP: call_tool(deal_list) MCP->>Child: pdcli deal list --output json --resolve-fields --yes Child->>PD: GET /api/v2/deals PD-->>Child: 200 JSON Child-->>MCP: stdout JSON, exit 0 MCP-->>Host: tool result Note over MCP,Child: --allow-writes adds ~14 write tools Note over MCP,Child: Timeout 120s or output over 16MB becomes tool error%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%% sequenceDiagram participant Host as MCP Host participant MCP as pdcli mcp serve participant Child as pdcli child process participant PD as Pipedrive API Host->>MCP: list_tools MCP-->>Host: 45 read tools (default scope) Host->>MCP: call_tool(deal_list) MCP->>Child: pdcli deal list --output json --resolve-fields --yes Child->>PD: GET /api/v2/deals PD-->>Child: 200 JSON Child-->>MCP: stdout JSON, exit 0 MCP-->>Host: tool result Note over MCP,Child: --allow-writes adds ~14 write tools Note over MCP,Child: Timeout 120s or output over 16MB becomes tool errorReviews (1): Last reviewed commit: "docs: MCP guide + agent-story refresh, a..." | Re-trigger Greptile