diff --git a/CLAUDE.md b/CLAUDE.md index b672c06f..e0642e9d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -619,6 +619,8 @@ After build passes, run `pnpm run test:unit` and fix any failures before committ For any non-trivial change (new feature, bug fix, behaviour change, or notable refactor), add an entry to the `[Unreleased]` section of `CHANGELOG.md` before finishing. Use the appropriate category (`Added`, `Changed`, `Fixed`, `Removed`). Skip purely internal changes such as test-only edits, code style fixes, or minor cosmetic/styling tweaks (e.g. changing colors, adjusting whitespace, renaming labels). The changelog is for **users reading release notes** — only include entries that a user would care about. Do not add entries for: new warnings or deprecation notices on existing commands, minor help text changes, test infrastructure, CI/CD changes, or internal refactors. When in doubt, leave it out. +Whenever a change touches the user-facing CLI surface — adding, renaming, or removing commands or flags, changing argument syntax, defaults, session states, or workflows — check the agent skill at `skills/mcpc/SKILL.md` (printed by `mcpc help --skill`) and update it so it keeps matching the actual CLI behaviour and README. The skill is a curated guide, not an exhaustive reference: it must never contradict the CLI, but it doesn't need to enumerate every flag — keep it concise and only add features that matter to agents. Purely internal changes don't need a skill update; as a rule of thumb, any change that warrants a `CHANGELOG.md` entry also warrants a quick skill check. + Keep each changelog entry to one or two short sentences focused on the user-visible behaviour. Do not enumerate implementation details, internal class names, or step-by-step breakdowns — readers want to know what changed for them, not how it was built. If an entry needs subheadings or its own bulleted breakdown, it's too long. When opening a pull request, always reference the originating issue or PR in the description (e.g. `Fixes #55`, `Refs #223`, `Supersedes #222`). This anchors the change to its motivation and lets reviewers see prior discussion, alternative fixes that were considered, and the failure mode being addressed. If the change is motivated by a Slack/email/internal thread with no GitHub artifact, open or link an issue first so future readers have a single source of truth. The same applies to commit messages for non-trivial changes: include `Fixes #N` / `Refs #N` in the body. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67ad79d8..887eaa67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,10 @@ server that works out of the box, so readers can copy-paste examples and run the This is a soft convention for documentation consistency, not a license condition — mcpc is distributed under Apache 2.0 and you are free to use it with any MCP server. +If your change touches the user-facing CLI surface (commands, flags, argument syntax, defaults, +or workflows), also update the built-in agent skill at [`skills/mcpc/SKILL.md`](./skills/mcpc/SKILL.md) +(printed by `mcpc help --skill`) so it keeps matching the CLI and README. + ## Development setup This repo uses [pnpm](https://pnpm.io/) 10 (pinned via `packageManager` in `package.json`). If you diff --git a/skills/mcpc/SKILL.md b/skills/mcpc/SKILL.md index cbe36624..5c0eaf43 100644 --- a/skills/mcpc/SKILL.md +++ b/skills/mcpc/SKILL.md @@ -91,11 +91,20 @@ mcpc @apify tools-call --help # shortcut for tools-get: that tool's de mcpc grep "search" # search tools + instructions across ALL sessions mcpc @apify grep "actor" --resources # search one session # grep filters: --tools/--resources/--prompts/--instructions, -E regex, -s case-sensitive, -m max +# grep exits 0 on match, 1 on no matches (grep convention) ``` Prefer progressive discovery: `grep` to find the right tool, then `tools-get` for its schema. This keeps token use low instead of dumping every tool definition. +For scripts and CI, pin a tool's schema to catch breaking changes early: + +```bash +mcpc --json @apify tools-get > expected.json # snapshot the schema +mcpc @apify tools-call --schema expected.json # fail fast if it drifted +# also on tools-get; --schema-mode strict | compatible (default) | ignore +``` + ## Calling tools (passing arguments) Arguments go after the tool name. Three interchangeable styles: @@ -168,6 +177,9 @@ mcpc logout mcp.apify.com # Bearer token — not stored as a profile; kept per-session mcpc connect mcp.apify.com @s -H "Authorization: Bearer $TOKEN" mcpc @s tools-list + +# Machine-to-machine (CI/CD, daemons) — client-credentials grant, no browser needed +mcpc login mcp.example.com --grant client-credentials --client-id my-svc --client-secret s3cr3t ``` With no auth flags, mcpc uses the `default` profile if one exists, otherwise it @@ -224,13 +236,14 @@ mcpc @apify skills-get --raw # print the SKILL.md markdown (pipe to a mcpc --verbose @apify tools-call # protocol-level detail (JSON-RPC, transport) mcpc @apify logs # bridge log; -n , --follow, --since 1h mcpc @apify ping # round-trip health check +mcpc @apify logging-set-level debug # ask the server to log more (server-side level) mcpc clean # tidy stale sessions/logs (also: mcpc clean all) ``` ## Exit codes - `0` — success -- `1` — client error (invalid arguments, unknown command) +- `1` — client error (invalid arguments, unknown command); `grep` also exits 1 on no matches - `2` — server error (tool failed, resource not found) - `3` — network error - `4` — authentication error