Files
PaperClipAI/tests
DottaandClaude Opus 5.5 78cf5aa81a feat(public-mcp): let paperclip_create_task assign a person or no one (#22011)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The public MCP endpoint (`/mcp/paperclip`) lets an outside
assistant, or another Paperclip instance, act in a company as a person.
> - The `paperclip_create_task` tool requires `assigneeAgentId`.
> - So every task that an outside caller files starts an agent run on
the receiving instance and spends its budget.
> - A colleague on another instance must be able to file work for a
person, or for nobody, without that cost.
> - This pull request makes the agent assignee optional and accepts
`assigneeUserId`, the same field the REST issues API uses.
> - The benefit is that instance-to-instance task filing does not spend
the receiving company's budget unless the caller picks an agent.

## Linked Issues or Issue Description

**Subsystem affected**
Public MCP endpoint (`/mcp/paperclip`), tool `paperclip_create_task`.

**Problem or motivation**
`paperclip_create_task` requires `assigneeAgentId`. A caller cannot
create a task for a person or an unassigned task. One Paperclip instance
can connect to another through the generic remote MCP connector, and
people use this to file tasks on a colleague's instance. Every such task
wakes an agent on the receiving instance and can spend its budget.

**Proposed solution**
Make `assigneeAgentId` optional and accept `assigneeUserId`, the same
field the REST issues API uses. Reject both at once. Only an agent
assignee starts a run. Add a read-only `paperclip_list_people` tool so
the caller can find a person's user ID.

**Alternatives considered**
A new MCP-only assignee field. We did not use it, because the REST API
already has `assigneeUserId` and its checks.

**Roadmap alignment**
This supports instance-to-instance communication through the public MCP
endpoint. It does not duplicate planned core work in ROADMAP.md.

## What Changed

- `paperclip_create_task`: `assigneeAgentId` is optional. The tool
accepts `assigneeUserId`, with the same shape as the REST issues API.
- `paperclip_create_task`: a schema refinement rejects a call that has
both assignees. The rejection occurs before the server writes an
idempotency receipt or a task.
- `paperclip_create_task`: the tool description says that an agent
assignee may start work and spend budget, and that a person or no
assignee does not start a run. The `scheduling` result text now matches
the assignee type.
- New read-only tool `paperclip_list_people`. It uses the existing `GET
/companies/:companyId/user-directory` route, which only needs company
access. It returns user ID, name and role. It does not return email.
- The task goes through the same REST create route as before. Company
scope, the `tasks:assign` decision (which also checks that a person is
an active member), activity logging and the service checks all still
apply.
- `doc/public-mcp.md`: documents the three assignee shapes and the new
tool.
- `tests/runner-e2e/public-mcp-grading.ts`: adds `paperclip_list_people`
to the read-only tool list.
- The stdio server (`packages/mcp-server`) already uses
`createIssueInputSchema`, which accepts both fields. It does not change.

## Verification

- New test in `server/src/__tests__/public-mcp.test.ts`. It uses the
real issue and access routes. It proves:
- a task for a person and an unassigned task are created as `todo`, and
their `requestId` replays return the same result;
  - neither shape wakes an agent, and the company has no heartbeat runs;
  - a task for an agent still wakes that agent one time;
- both assignees at once are rejected with a clear message, and no
receipt is written;
- a member of another company is rejected (HTTP 403 from the REST
assignment check), with a result identical to a user ID that does not
exist;
- `paperclip_list_people` returns members without email and without
other companies' users.
- Red first: the test failed with "Unknown Paperclip operation" before
the change. Green after the change.
- `cd server && npx vitest run src/__tests__/public-mcp.test.ts`: 85
passed (also after the rebase on `origin/master`).
- `npx vitest run --config tests/runner-e2e/vitest.config.ts
tests/runner-e2e/public-mcp-grading.test.ts
tests/runner-e2e/public-mcp-expanded-flow.test.ts
tests/runner-e2e/public-mcp-invitation-grading.test.ts`: 81 passed.
- `cd server && npx tsc --noEmit -p .`: passed.
- `pnpm verify` exits 2 because a doc changed (a global CI input). CI
supplies the broad coverage.

## Risks

- Low risk. The change only adds optional input. Existing calls with
`assigneeAgentId` behave the same.
- An unassigned task is created as `todo`, the same status as before. No
code path wakes an agent for a task without an agent assignee.
- `paperclip_list_people` shows member names and roles to any connection
with read scope. The same data is already available to any company
member in the UI assignee picker through the same route.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code, with tool
use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:42:31 -06:00
..