Repository navigation
Unify argument parsing between MCP handlers and agent tool executor #1060
Copy link
Copy link
Closed
Labels
Description
Problem
Issue #1040 established the shared ops/ layer so both MCP handlers and local agent tool executors delegate to the same business logic. However, the argument parsing layer above ops still diverges:
- MCP handlers (
packages/core/src/mcp/handlers/nodes.rs): Accept flat properties (e.g.,{"id": "...", "status": "done"}) and pass them through to the ops layer, which handles namespacing. - Local agent tool executor (
packages/agent/src/local_agent/tools.rs): Previously required the model to wrap properties in a"properties"object (e.g.,{"id": "...", "properties": {"status": "done"}}). This was partially fixed inline but not systematically aligned.
This divergence means the 8B model's flat tool calls fail on the agent path but would succeed via MCP.
Specific Gaps
- Argument normalization: MCP handlers and agent tool executors parse arguments differently — no shared "args → typed input" adapter.
- Property flattening: The agent executor now collects unknown top-level keys into
properties, but this logic is duplicated inline rather than shared. - Error handling: MCP handlers return MCP error codes; agent executor returns
ToolErrorvariants. Error messages differ for the same underlying failure. - Tool definitions: The agent defines tool schemas in
tools.rs(def_create_node(), etc.) while MCP defines them inhandlers/. These can drift apart.
Proposed Solution
Extract a shared argument adapter layer that both MCP handlers and agent tool executors use:
Model/Client → Argument Adapter (shared) → ops/ layer → NodeService
Options:
- Option A: Move argument parsing into the ops layer itself (ops functions accept
Valueand parse internally) - Option B: Create
ops::argsmodule withparse_create_node_args(Value) → CreateNodeInput, etc. - Option C: Generate tool definitions + argument parsers from a single schema definition
Prior Work
- Issue Refine local agent system prompt for better tool usage and response quality #1040: Created ops layer (core business logic shared)
- Issue Semantic skill discovery via find_skills tool for 8B model and external agents #1051/1055: Unified
find_skillsviaskill_ops(model for future unification) - Issue Unify skill/prompt seeding with markdown import pipeline #1056: Unify seed/import pipelines (related but different scope)
Acceptance Criteria
-
create_nodeandupdate_nodeargument parsing is shared between MCP and agent executor - Flat properties are accepted uniformly (no
"properties"wrapper required) - Tool schema definitions are generated from a single source (no drift)
- Error messages are consistent between MCP and agent paths
-
find_skillspattern (shared ops function) extended to remaining tools
Reactions are currently unavailable
Activity
Add dedicated create_schema and update_task_status tools, fix skill p…
malibio commentedon Apr 7, 2026
Additional finding: Tool definition schema drift causes runtime failures
The
create_schemaagent tool definition drifted from the MCP handler'sSchemaRelationshipstruct:target→ MCP expectstargetType(camelCase serde)directionandcardinality→ MCP requires them (not Optional)field_type→ MCP expectstype(serde rename)core_values→ MCP expectscoreValues(camelCase)These were fixed manually but will recur unless tool definitions are generated from the same source as the MCP handler structs.
Concrete task for unification:
def_create_schema()tool definition must matchCreateSchemaParams,SchemaField, andSchemaRelationshipserde formats exactlyschemarscrate or a build-time codegen step)Address code review: DRY namespace helpers, validate task status, fix…
malibio commentedon Apr 7, 2026
Baseline: 128 test files, 3918 tests passed
Fix local agent document reading: get_node markdown, search_semantic …
Fix local agent document reading (get_node markdown, search_semantic,…
Add dedicated create_schema and update_task_status tools, fix skill p…
Address code review: DRY namespace helpers, validate task status, fix…
Fix local agent document reading (get_node markdown, search_semantic,…