Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agents/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
adding it. `--dry-run` prints the write request instead of sending it (a write tool takes
`dry_run: true` for the same plan), the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
6 transient).
- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50
Expand Down
3 changes: 2 additions & 1 deletion .claude/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
adding it. `--dry-run` prints the write request instead of sending it (a write tool takes
`dry_run: true` for the same plan), the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
6 transient).
- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50
Expand Down
3 changes: 2 additions & 1 deletion .opencode/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
adding it. `--dry-run` prints the write request instead of sending it (a write tool takes
`dry_run: true` for the same plan), the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
6 transient).
- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50
Expand Down
8 changes: 7 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,13 +148,19 @@ program stays a test.
the CLI asks before it sends it, as before a delete, and the tool carries
`_meta["anthropic/requiresUserInteraction"]` (`GRANTS_ACCESS`), which a client that honours
it answers by asking a person on every call. No list of such operations exists anywhere.
A tool that writes takes `dry_run` and then sends nothing: the one way a tool reaches a
service is the client `client_provider` builds for it, which under `dry_run` carries the
core's guard, so no tool has a second way to a service and none declares the argument.
- **Why:** agents and their hosts decide what to auto-approve from these hints; the MCP default
for an unannotated tool is "destructive".
- **Check:** the contract test (`tests/contract/test_contract.py`, one case per way of reaching an
operation, fail-closed both ways) runs every tool and compares its hints with the strongest
effect of the endpoints it sends, and its `GRANTS_ACCESS` mark with whether one of them grants
access, both ways; `test_the_help_of_a_command_says_it_grants_access_where_its_tool_is_marked`
holds the command's help to the same mark; `test_arch3_effect_overrides_are_marked` keeps
holds the command's help to the same mark;
`test_every_tool_that_writes_takes_its_client_from_the_one_guarded_place` holds every writing
tool to the provider, and the contract test runs every write case under `dry_run` on both
surfaces: the same plan, and no write sent; `test_arch3_effect_overrides_are_marked` keeps
`# violation(arch-3): <reason>` above every `effect=`, and every such marker above one;
`test_arch3_write_tools_carry_write_tag` keeps `--read-only` complete over the served tools,
and the ast-grep rule `no-tool-tags` keeps a second statement out. `status_get`, the one
Expand Down
17 changes: 17 additions & 0 deletions docs/en/how-to/serve-the-mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,23 @@ Every tool says what it does: reads carry `readOnlyHint`, writes say whether the
or idempotent. A host can auto-approve reads and ask before a destructive call. `--read-only`
removes every write, for a deployment where the agent must not change anything.

A tool that grants access (a role, a permission, an access binding, an embedding) is marked so
that a client which honours the mark asks a person on every call, and says so in its description.

## Preview a write

Every tool that writes takes `dry_run`. With `dry_run: true` it sends nothing and answers the
request it would have sent, the same object `ycli … --dry-run -o json` prints, with secrets masked:

```json
{"dry_run": true, "request": {"method": "PATCH", "url": "https://api.tracker.yandex.net/v3/issues/DE-7", "body": {"summary": "New"}}}
```

- What the tool reads before its first write is read; the plan is of the first write only. One tool makes several: `wiki_attachments_upload` plans the opening of its upload session.
- `request` is `null` where the tool would write nothing.
- A tool that only reads has no `dry_run`: there is nothing to plan, and the argument is refused. The CLI differs: `--dry-run` is an option of every command, and a read under it goes out.
- A tool that grants access prompts for a person on a dry run too: the client decides from the tool, before the server sees the arguments. Where nobody can be asked, plan it with the command: `ycli … --dry-run`.

## Prompts and resources

Besides tools, the server offers a few prompts and resources. A client shows a prompt as a ready request (in Claude Code, `/yandex-360:tracker_issue_brief DE-7`) and lets you attach a resource to the conversation (`@yandex-360:ycli://tracker/issue/DE-7`).
Expand Down
Loading
Loading