Make wrapped Pydantic `input` tools robust to MCP clients that serialize object args as JSON strings

[AndreaV-Lsi]

Summary

Tools whose sole parameter is a wrapped Pydantic model named input
(create_work_package, update_work_package, …) fail for any MCP client that serializes
object-typed arguments as a JSON string. Spec-compliant clients that send a JSON object
work unchanged. The defect is in argument-serialization compatibility, not in the server's
business logic.

Goal: a general, widely-consumable fix so the server works with any MCP client regardless of
how it serializes structured tool arguments — not a workaround for one product.

Symptom

1 validation error for call[create_work_package]
input
  Input should be a valid dictionary or instance of CreateWorkPackageInput
  [type=model_type, input_value='{"project_id": 458, ...}', input_type=str]

input_value is valid JSON, but it arrived as a str.

Root cause

@mcp.tool
async def create_work_package(input: CreateWorkPackageInput) -> str:
    ...

FastMCP publishes input with an opaque object schema (an unconstrained / $ref shape, not
an explicit type: object) and validates the argument against the model before the function
body runs. So success depends entirely on how the client encodes the argument:

• Client sends input as a JSON object → validates to the model → works.
• Client serializes object-typed args as a JSON string (common when the parameter schema
  isn't an explicit object) → FastMCP receives a str → rejects it before the body. An in-body
  json.loads cannot help, because validation happens first.

Evidence it is client-side, not server-side

Two independent pristine clones (same HEAD, no local diffs, no edits):

• Driven by a spec-compliant client (Claude Code / VS Code extension): work-package creation
  succeeds unpatched — the client sends input as an object.
• Driven by a client that stringifies object args: the model_type error above.

Within the failing client, read tools and flat-parameter tools work fine
(e.g. set_work_package_parent(child_id, parent_id), every list_*). Only the
single-wrapped-input tools fail. This localizes the issue precisely to serialization of object
arguments under an opaque parameter schema.

Why fix it server-side

The MCP ecosystem has many clients and bridges. Tolerating both encodings is cheap server hygiene
that broadens compatibility to the whole class of "stringifying" clients without asking any of
them to change. It is not specific to any one product.

Scope — affected tools (verified against current HEAD)

grep -rn "async def .*(input:" src/tools → 17 functions across 8 files:

File	Functions
src/tools/work_packages.py	create_work_package, update_work_package
src/tools/relations.py	create_work_package_relation, update_work_package_relation
src/tools/projects.py	create_project, add_subproject, update_project
src/tools/versions.py	create_version
src/tools/time_entries.py	create_time_entry, update_time_entry
src/tools/memberships.py	create_membership, update_membership
src/tools/news.py	create_news, update_news
src/tools/weekly_reports.py	generate_weekly_report, get_report_data, plus internal _generate_weekly_report_impl (verify call path)

Whatever fix is chosen should ideally cover any future model-input tool automatically.

Candidate solution directions (to be discussed before implementation)

To be evaluated in the issue discussion — not yet decided:

1. Decorator / wrapper that auto-detects the model parameter and coerces a str argument via
   json.loads → model before the body runs.
2. Pydantic BeforeValidator / model_validator(mode="before") on each input model (or a
   shared base model) that accepts str | dict.
3. Flatten the signatures — drop the input wrapper and expose explicit fields so FastMCP
   emits an explicit type: object schema (larger API change; affects docs/tests).
4. Custom type annotation (Annotated[Model, BeforeValidator(...)]) applied uniformly.

Each has trade-offs in blast radius, schema impact, test surface, and "covers future tools
automatically." We will compare these (and a parallel proposal from another session) here before
writing code.

Acceptance criteria

• A client that sends input as a JSON string can successfully call all affected tools.
• A spec-compliant client that sends input as a JSON object continues to work (no regression).
• The fix covers all 17 current call sites and, ideally, any future model-input tool without
  per-tool boilerplate.
• The published tool JSON schema remains valid; no breaking change for already-working clients.
• Tests cover both encodings (object and stringified) for at least a representative tool.
• uv run black . / uv run flake8 . clean.

Out of scope

• Changing OpenProject API client logic or any tool's business behavior.
• Reworking flat-parameter tools (they already work).
• Bumping/pinning FastMCP beyond what the fix requires.

References

• Affected files: see scope table.
• FastMCP >=2.0.0, pydantic >=2.0.0 (pyproject.toml).
• Local planning mirror: LOCAL_PR_BACKLOG.md (to be promoted to this issue's PR).

[AndreaV-Lsi]

Decision (agreed) — converged approach

Two independent proposals were compared and a synthesis was chosen.

Empirical verification (pydantic 2.11.7, repo's pinned version)

• model field <- JSON string → fails with model_type (reproduces the reported bug).
• model_validator(mode="before") on the model → rescues the string before the model_type
  rejection (str → model). dict still works.
• Union[Model, str] → accepts the string but leaves it a str (requires body/wrapper coercion).

Both candidate mechanisms are therefore correct. We choose the one with the least coupling and the
cleanest published schema.

Chosen mechanism — "synthesis"

1. CoercibleModel base in src/utils/inputs.py with a model_validator(mode="before") that
   json.loads a str and passes dict/model through. All wrapped-input models subclass it.
   • No FastMCP-introspection coupling (pure pydantic).
   • Keeps a clean object schema (no anyOf[object,string] that could tempt clients to start
     stringifying).
2. Keep an as_model(model_cls, value) helper (from the parallel proposal) for non-decorated
   call paths — notably the internal _generate_weekly_report_impl.
3. Tripwire test asserting every *Input model under src/tools/ subclasses CoercibleModel,
   so future model-input tools are covered without runtime metaprogramming.
4. Tests for both encodings (object + JSON string) on the helper and a representative tool.

We deliberately do not use the coerce_model_input decorator that overrides
__signature__/__annotations__: its "auto future coverage" benefit is replaced by the tripwire
test, without coupling to FastMCP's signature introspection.

Also in this PR — flatten the two hot tools (Option 2, scoped)

create_work_package and update_work_package migrate from a wrapped input: Model to explicit
typed parameters. This removes the opaque parameter that triggers stringification entirely and
yields a self-describing schema for those two highest-traffic tools.

Notes / sub-decisions this creates:

• Interface change for those 2 tools: the published input schema changes from { "input": {…} }
  to flat fields. LLM-driven MCP clients re-read the schema each session, so this is transparent in
  practice; flagged here for completeness.
• The now-unused CreateWorkPackageInput / UpdateWorkPackageInput models and their references in
  test_tools.py will be updated/removed accordingly.
• The remaining ~15 wrapped-input tools keep their models and gain the CoercibleModel safety net
  in this PR; flattening them is out of scope (future incremental work item).

Acceptance criteria

• A client sending input as a JSON string succeeds for all still-wrapped tools.
• A client sending input as a JSON object still works (no regression).
• Flattened create_/update_work_package work via explicit params and produce an object schema.
• Tripwire test fails if a new *Input model forgets the base.
• Both-encoding tests pass; uv run black . / flake8 . clean.

Out of scope

• Flattening the other 15 wrapped tools (separate future issue).
• Any OpenProject client/business-logic change.

[AndreaV-Lsi]

🧪 Testing handoff — branch fix/input-arg-serialization

The fix is implemented and pushed to the fork (commit c3dbeff). It needs validation from
two MCP clients with different argument-serialization behavior before we open an upstream PR.

Local checks already green: server loads all tools; create_work_package/update_work_package
publish a flat object schema (no $defs); wrapped tools keep their schema; 11/11 pytest pass;
no new flake8 issues.

Get the branch

If you have a clone of this fork (LS-Instruments):

git fetch origin && git checkout fix/input-arg-serialization

If your clone points at upstream (AndyEverything):

git remote add lsi https://github.com/LS-Instruments/openproject-mcp-server.git
git fetch lsi && git checkout -b fix/input-arg-serialization lsi/fix/input-arg-serialization
uv sync --extra dev

Point your MCP client at this checkout's openproject-mcp-fastmcp.py (with PYTHONPATH = repo
root) and a .env containing real OPENPROJECT_URL / OPENPROJECT_API_KEY, then restart the
client. ⚠️ These tools create real data — use a throwaway test project and clean up after
(delete_work_package, delete_project).

Roles

• Session A — the client that serialized object args as a JSON string (reproduced the original
  model_type error). This is the primary validator: it must now succeed.
• Session B — a spec-compliant client (sends objects; worked before). This is the regression
  check: it must keep working, including the newly flattened tools.

Tool-call matrix

Tool	Kind after fix	Session A (stringifying)	Session B (compliant)
create_work_package	flattened (explicit params)	must succeed	must succeed
update_work_package	flattened (explicit params)	must succeed	must succeed
create_project	wrapped + CoercibleModel	must succeed (key test)	must succeed
create_time_entry	wrapped + CoercibleModel	must succeed	optional
create_news	wrapped + CoercibleModel	must succeed	optional
create_work_package_relation	wrapped + CoercibleModel	must succeed	optional

The flattened tools prove the opaque-parameter issue is gone; the wrapped tools prove the
CoercibleModel JSON-string safety net works end-to-end through FastMCP.

Please paste results back here

### Session <A|B> — client: <name + version>
branch/commit: c3dbeff
- create_work_package:            PASS / FAIL  (notes)
- update_work_package:            PASS / FAIL  (notes)
- create_project:                 PASS / FAIL  (notes)
- create_time_entry:              PASS / FAIL / not run
- create_news:                    PASS / FAIL / not run
- create_work_package_relation:   PASS / FAIL / not run
- Any model_type / other errors:  <paste verbatim>

Once both sessions report green, we open the PR to AndyEverything/openproject-mcp-server.

[AndreaV-Lsi]

Follow-up to the external test feedback — pushed 5151486

Thanks for the thorough pass. The serialization fix was confirmed correct; here's how the three
action items were handled (new commit 5151486 on fix/input-arg-serialization, on top of
c3dbeff):

1. percentage_done read-only (HTTP 422 PropertyIsReadOnly) — fixed + documented.
update_work_package now attempts the update and, if the instance rejects percentageDone as
read-only, drops that field and retries once so the rest of the update still applies. If
percentage_done was the only field, it returns a clear message instead of a confusing 422. The
param is kept (other instances allow it). Detection is conservative — it only retries when the
error is specifically about percentage being read-only, so unrelated errors are not swallowed.
Noted in the docstring and the README. Covered by tests/test_update_readonly.py (retry path,
only-field message, non-read-only error propagation).

2. Live coverage of the flattened payload — added.
tests/test_integration_smoke.py does a real create → get → update(status) → delete round-trip
through the flattened tools (exercising payload-building, not just signatures), and cleans up the
work package it creates. Skipped by default; enable with:

OPENPROJECT_SMOKE=1 OPENPROJECT_URL=... OPENPROJECT_API_KEY=... \
OPENPROJECT_TEST_PROJECT_ID=458 OPENPROJECT_TEST_TYPE_ID=1 [OPENPROJECT_TEST_STATUS_ID=...] \
uv run pytest tests/test_integration_smoke.py -v

3. Test-infra note — no repo change needed.
.venv is gitignored (never committed); CI/Linux builds its own env via uv sync --extra dev.
The root test_tools.py is an intentionally manual live script, outside testpaths=["tests"].

Local suite: 14 passed, 1 skipped (smoke), no new flake8 issues.

Re-validation requested

• Session A / B: please re-run against 5151486 (git pull), focusing on
  update_work_package with percentage_done on the read-only instance — expect the rest of
  the update to apply plus a "percentage_done is read-only … skipped" note, not a 422.
• If you have a disposable test project, running the gated smoke test above would give us the live
  create/update payload coverage end-to-end.

[AndreaV-Lsi]

fastmcp version cap — pushed e528c3f

Thanks for the re-validation and the catch on the version range.

Addressed the new action item: pyproject.toml now pins fastmcp>=2.0.0,<3. The code/tests use the FastMCP 2.x tool API (@mcp.tool → FunctionTool.fn); 3.x changes the decorator's return type, so a lockless pip install that resolved fastmcp 3.x broke the suite. The cap matches the committed lock (resolves fastmcp 2.13.2) and the API actually used, so non-uv installs and CI won't silently pull an incompatible major version. Adding full 3.x support is deferred (would need the runtime re-verified on 3.x, not just the .fn access) — tracked separately if wanted.

Suite after the cap: 14 passed, 1 skipped.

Still outstanding (not blocking the fix): the gated live smoke test (create→get→update→delete through the flattened tools) hasn't been run against the real instance yet — needs to run where the instance is reachable (OPENPROJECT_SMOKE=1 …).

[AndreaV-Lsi]

Upstream baseline results + a fix it surfaced

A baseline smoke test was run on unpatched upstream (a3a71f4, fastmcp 2.13.2, pydantic 2.11.7, instance Core 17.5.1) by a spec-compliant admin client. Result: all core ops green — connectivity, reads, work-package create/get(via search)/update(subject+status)/delete, and a news create/get/delete round-trip — with one expected failure:

update_work_package + percentage_done →
API Error 422 PropertyIsReadOnly: "% Complete was attempted to be written but is not writable."
(attribute: percentageDone)

Interpretation — no regression, strict improvement. On upstream, sending percentage_done to this instance fails the entire update with that 422. Our branch detects exactly this error, drops the field, retries, and applies the rest with a note — so the only behavioral difference vs baseline is the one we intended to fix. Everything else matches.

Bug the baseline caught in our own test (fixed in 0228407): this server has no standalone get_work_package tool (only search_work_packages; get_work_package exists solely as a client method). Our test_integration_smoke.py imported get_work_package, so it would have ImportError'd when actually run. Fixed: read back via search_work_packages, and tool imports moved to module top so a missing/renamed tool now fails pytest collection even when the live test is skipped. Suite: 14 passed, 1 skipped.

Note (separate concern): the README documents get_work_package as tool AndyEverything#12, but it isn't implemented as a tool — a doc/implementation mismatch that fits the README-fixups backlog item (#4).

Branch head: 0228407. Still outstanding: running the gated live smoke test on our branch against the instance (the baseline above was upstream).

[AndreaV-Lsi]

Branch live smoke test — PASS (matches baseline except the intended fix)

Ran against the live instance via the MCP server, which was already serving fresh branch code (PID restarted since the earlier handoff; verified the advertised create_/update_work_package schemas are flat + carry the read-only note — no kill/reconnect needed).

### Branch smoke test (fix/input-arg-serialization)
env: repo=fork, HEAD=0228407, fastmcp=2.13.2, pydantic=2.11.7, instance=Core 17.5.1
test project: #461 ([smoke-branch-v2] temporary, created + deleted), type: 1 (Task), status used: 7 (In progress)

Step 1 connectivity:   test_connection PASS | check_permissions PASS (admin)
Step 2 reads:          list_projects PASS (20) | list_types PASS (7) | list_statuses PASS (15) | list_work_packages PASS (empty new project)
Step 3 WP CRUD:
  - create (flat):     PASS  (id=7705; called with FLAT params, no input wrapper)
  - read (search):     PASS  (search_work_packages query=7705)
  - update subj+status:PASS  (status_id 7 -> "In progress")
  - update +percentage_done: PASS  -- verbatim:
      "✅ Work package #7705 updated successfully! ... Subject: [smoke-branch] wp (pct test) ... Status: In progress
       ⚠️ percentage_done is read-only on this instance and was skipped; the other fields were updated."
      (NO 422 — subject applied, percentage_done skipped with note)
  - delete:            PASS
Step 4 news CRUD:      create PASS (id=4, wrapped tool via object input) | get PASS | delete PASS
Step 5 cleanup:        clean — list_work_packages empty, list_news empty, delete_project #461 PASS. No leftovers.

Comparison vs upstream baseline (a3a71f4): IDENTICAL everywhere EXCEPT
update +percentage_done, which flips from baseline 422 PropertyIsReadOnly -> branch success-with-note.

Conclusion: the branch regresses nothing the baseline did, and fixes the one path it targeted. Flattened WP tools work live with flat params; wrapped tools (create_project, create_news) still work with object input. Combined with the network-free suite (14 passed, 1 skipped) and the unit-tested read-only retry, PR-4 is validated.

[AndreaV-Lsi]

Cowork (stringifying-client) path — validated live end-to-end

Simulated a client that serializes object-typed MCP args as a JSON string (the original failure mode) using a fastmcp.Client that sends create_project's input as a str over the wire:

=== create_project, input as JSON STRING (type sent: str) ===
wire arg type: str
✅ Project created successfully!  **ID**: #463 ...
=== cleanup delete_project ===
✅ Project #463 deleted successfully

The branch server accepted the JSON-string input via CoercibleModel and created the project — the exact call that fails with model_type on upstream. Combined with the earlier object-encoding live run, both client encodings are now proven live: object-sending (no regression) and stringifying (the fix). Cleaned up; no leftovers.