Skip to content

Comments

feat: refactor plan-execute agentic orchestration in custom MCP client#154

Merged
DhavalRepo18 merged 25 commits intomainfrom
feat/151-mcp-plan-execute-client
Feb 19, 2026
Merged

feat: refactor plan-execute agentic orchestration in custom MCP client#154
DhavalRepo18 merged 25 commits intomainfrom
feat/151-mcp-plan-execute-client

Conversation

@ShuxinLin
Copy link
Collaborator

@ShuxinLin ShuxinLin commented Feb 18, 2026 •
edited
Loading

Summary

Implements #151 — refactors the plan-execute agentic orchestration layer to run within a custom MCP client, replacing/augmenting the existing AgentHive framework.

Motivation

The current src/agent_hive/ plan-and-execute sequential workflow relies on bespoke orchestration logic. Moving this into a custom MCP client enables:

  • Standardized tool/server communication via MCP protocol
  • Better composability with existing MCP servers (IoT, utilities, etc.)
  • Cleaner separation between orchestration logic and domain agent tools

Checklist

  • Design custom MCP client with plan-execute loop
  • Map existing AgentHive planning and execution steps to MCP tool calls
  • Integrate domain agents (IoT, FMSR, TSFM, WorkOrder) as MCP tool providers
  • Add/update tests for the new orchestration layer

References

@ShuxinLin
feat: initialize plan-execute MCP client scaffold (issue #151)
a50aa22 
Empty commit to open tracking PR for refactoring AgentHive
orchestration into a custom MCP client.

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin ShuxinLin force-pushed the feat/151-mcp-plan-execute-client branch from 2108550 to a50aa22 Compare February 18, 2026 18:50
@ShuxinLin
feat(mcp/client): add data models and LLM backend abstraction
ae76447 
- PlanStep, Plan (with topological resolved_order), StepResult,
  OrchestratorResult dataclasses in models.py
- Abstract LLMBackend interface and WatsonXLLM concrete implementation
  (integer model IDs: 16=llama-4-maverick, 19=granite-3-3-8b)

Closes #151 (partial)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
feat(mcp/client): add planner, executor, and orchestrator
9ab025d 
Planner (maps AgentHive PlanningWorkflow):
- LLM decomposes question into #Task/#Agent/#Dependency/#ExpectedOutput steps
- parse_plan() reuses the same regex format as PlanningWorkflow.generate_steps()

Executor (maps AgentHive SequentialWorkflow + ReactAgent):
- Per-step: queries assigned MCP server for tools via stdio transport
- LLM selects the best tool and generates its arguments
- Calls the tool via mcp.ClientSession / stdio_client
- Handles unknown agents, tool call errors, and direct answers from context

Orchestrator (PlanExecuteOrchestrator):
- Discover → Plan → Execute → Summarise pipeline
- server_paths is injectable for testing / future server additions

Closes #151 (partial)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
feat(mcp/client): add unit tests and fix server_paths falsy-empty bug
f61d268 
Tests (36 total across 3 modules):
- test_models: Plan.resolved_order() topological sort (no deps, linear,
  diamond, parallel, empty), get_step(), StepResult.success
- test_planner: parse_plan() regex parsing for tasks/agents/deps/outputs,
  Planner.generate_plan() prompt injection and LLM delegation
- test_orchestrator: full orchestrator run, unknown agent error path,
  direct-answer (tool=null) path; Executor unknown-agent; _parse_tool_call
  variants (plain JSON, markdown fence, embedded JSON, unrecoverable)

Bug fix: Executor.__init__ used server_paths or DEFAULT_SERVER_PATHS
which silently ignored an explicitly passed empty dict; changed to
if server_paths is None check.

Closes #151 (partial)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
chore(mcp): add optional watsonx dependency for WatsonXLLM backend
ac06f62 
ibm-watsonx-ai is not required for the core orchestration framework or
tests (which use mock LLMs). Add it as an optional extra so production
deployments can opt in:

  pip install "assetopsbench-mcp[watsonx]"

Closes #151 (partial)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor(mcp): rename client/ → plan_execute/, orchestrator → runner
996be4b 
- mcp/client/ → mcp/plan_execute/ (package rename)
- orchestrator.py → runner.py; PlanExecuteOrchestrator → PlanExecuteRunner
- test_orchestrator.py → test_runner.py
- Update all imports and mock patch paths throughout

No functional changes.

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
docs(mcp): document plan_execute runner usage and tests in README
1291538 
- Replace the [WIP] stub with a full Plan-Execute Runner section:
  how it works (4-step loop), usage example, bring-your-own-LLM,
  adding more MCP servers via server_paths
- Update Running Tests to include plan_execute/tests/ commands and
  a combined one-liner for the full non-integration suite
- Update Architecture diagram to reflect the plan_execute package
  structure (Planner → Executor → Summariser → MCP servers)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
feat(mcp): add plan-execute CLI entry point
d979cfc 
plan_execute/cli.py:
- plan-execute <question> runs the full plan-execute workflow
- --model-id INT   select WatsonX model (default: 16)
- --server NAME=PATH  register additional MCP servers (repeatable)
- --show-plan     print the generated plan before execution
- --show-history  print each step result after execution
- --json          emit answer + plan + history as JSON

pyproject.toml:
- Register plan-execute = "plan_execute.cli:main" under [project.scripts]
- Add hatchling build-system with packages = ["plan_execute"] to fix
  multi-package discovery error and enable entry point installation
- Add tool.uv.package = true

README: document CLI flags, examples, and python-api usage side by side

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: promote mcp/ to src-layout — move project config to repo root
f195020 
Treat mcp/ as the source directory (like src/) with the repo root as the
project entrypoint. All uv/hatchling/pytest commands now run from root.

Moved to repo root:
  mcp/pyproject.toml   → pyproject.toml
  mcp/uv.lock          → uv.lock
  mcp/.python-version  → .python-version
  mcp/docker-compose.yaml → docker-compose.yaml

Updated pyproject.toml:
  - packages = ["mcp/plan_execute"]   (was "plan_execute")
  - pythonpath = ["mcp"]              (was ["."])
  - readme = "mcp/README.md"

Updated mcp/README.md:
  - All uv/pytest commands use mcp/ prefix (e.g. mcp/servers/iot/...)
  - Claude Desktop --project flag points to repo root

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
docs: move mcp/README.md → INSTRUCTIONS.md, add redirect in README.md
b9ffad3 
- mcp/README.md → INSTRUCTIONS.md (repo root)
- pyproject.toml: readme = "INSTRUCTIONS.md"
- README.md: add MCP Environment section under AI Agents pointing to INSTRUCTIONS.md

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: move docker-compose.yaml into mcp/couchdb/
974d5cc 
- docker-compose.yaml → mcp/couchdb/docker-compose.yaml
- Update volume bind-mount paths (drop couchdb/ prefix now that the
  compose file is colocated with couchdb_setup.sh and sample_data/)
- INSTRUCTIONS.md: all docker compose commands use
  -f mcp/couchdb/docker-compose.yaml

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
fix(llm): replace ibm_watsonx_ai SDK with direct REST client
9627307 
ibm_watsonx_ai is incompatible with Python 3.14 — its StrEnum subclass
calls super().__init__(*args, **kwargs) which Python 3.14 rejects with
TypeError: object.__init__() takes exactly one argument.

WatsonXLLM now uses requests (already a core dep) to call the WatsonX
REST API directly:
- IAM token endpoint for auth (with 60-second early-refresh cache)
- /ml/v1/text/generation for inference

Drop ibm-watsonx-ai from optional deps in pyproject.toml and remove
the install step from INSTRUCTIONS.md — no extra install needed.

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
docs: improve INSTRUCTIONS.md with ToC, env vars table, server tool r…
1f238c6 
…eference, and clearer structure

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: move .env to repo root, add WatsonX env vars
db2ca03 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: extract llm/ package, add --platform cli arg
6c3a47d 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: change model_id from int to string, drop MODEL_MAP
fe449e4 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: rename .env to .env.public, gitignore .env
fbc77db 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
improve: separate logging from output in CLI, add --verbose flag
6665231 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
refactor: planner selects tool+args, executor calls directly (1 LLM c…
1e45019 
…all per run)

Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
Base automatically changed from mcp-refactor to main February 19, 2026 00:02
@ShuxinLin
feat: add LiteLLM env vars to .env.public
32a13a1 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
feat: implement LiteLLM backend (Anthropic Messages API)
a0adf41 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
fix: add trailing newline to .gitignore
752f8fc 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
fix: load .env in CLI via load_dotenv()
e02ef18 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
fix: include tool and tool_args in --show-plan and --json output
8c059b3 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin
feat: LLM-based arg resolution for dependent steps
8e5f597 
Signed-off-by: Shuxin Lin <linshuhsin@gmail.com>
@ShuxinLin ShuxinLin force-pushed the feat/151-mcp-plan-execute-client branch from e92eb1c to 8e5f597 Compare February 19, 2026 20:15
@ShuxinLin ShuxinLin mentioned this pull request Feb 19, 2026
Closed
4 tasks
@ShuxinLin
Copy link
Collaborator Author

ShuxinLin commented Feb 19, 2026

Checklist evaluation

All four items from the PR description are complete:

Item Status Notes
Design custom MCP client with plan-execute loop ✅ Done mcp/plan_execute/ — runner.py, planner.py, executor.py, models.py, cli.py
Map AgentHive planning/execution steps to MCP tool calls ✅ Done Single LLM call for planning (tool + args included in plan); executor calls MCP servers directly via stdio. {{step_N}} placeholders resolved by a targeted LLM call for dependent steps.
Integrate domain agents as MCP tool providers ✅ Done IoT and Utilities servers fully wired. Additional servers (FMSR, TSFM, WorkOrder) pluggable via --server NAME=PATH or server_paths API — tracked as future work.
Add/update tests for orchestration layer ✅ Done 55+ unit tests across test_models.py, test_planner.py, test_runner.py; no live services required.

Marking ready for review.

@ShuxinLin ShuxinLin marked this pull request as ready for review February 19, 2026 20:39
@DhavalRepo18 DhavalRepo18 merged commit c602f7f into main Feb 19, 2026
1 check passed
@ShuxinLin ShuxinLin deleted the feat/151-mcp-plan-execute-client branch February 20, 2026 16:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@DhavalRepo18 DhavalRepo18 Awaiting requested review from DhavalRepo18

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat: refactor plan-execute agentic orchestration in custom MCP client

2 participants

@ShuxinLin @DhavalRepo18