feat(domain): add pluggable ai tool system with mcp server lifecycle management by arielshad · Pull Request #555 · shep-ai/shep

arielshad · 2026-04-14T06:44:16Z

Summary

Introduces a complete AI-native tool plugin system that lets users register, configure, and activate external tools (MCP servers, CLI tools, hook-based plugins) into Shep's agentic SDLC workflows.

TypeSpec domain models: Plugin entity, ToolGroup model, PluginType/PluginTransport/PluginHealthStatus enums
Persistence layer: SQLite migration, PluginMapper (bidirectional), PluginRepository with full CRUD
8 use cases: AddPlugin, RemovePlugin, ListPlugins, EnablePlugin, DisablePlugin, ConfigurePlugin, CheckHealth, GetCatalog
Infrastructure services: PluginHealthCheckerService (multi-tier runtime/env validation), McpServerManagerService (process lifecycle), curated plugin catalog (MemPalace, Token Optimizer, Ruflo)
Agent integration: MCP config path injection into AgentExecutionOptions, Claude Code executor --mcp-config flag support, feature agent worker plugin startup/shutdown lifecycle
CLI commands: Full shep plugin command group with 8 subcommands (add, remove, list, enable, disable, configure, status, catalog)
Web UI: Plugin management page with Installed/Catalog tabs, catalog browser with type badges and install buttons, sidebar navigation, per-feature plugin toggles in create-feature drawer
DI container: All service/use-case registrations with string token aliases for web routes

Evidence

Web UI - Installed Plugins Tab (empty state)

Web UI - Plugin Catalog Browser

Web UI - Sidebar Navigation with Plugins

Web UI - Create Feature Drawer with Plugin Toggles

Test Results

6,165 unit tests passing across 437 test files (includes 135 plugin-specific tests across 13 files)
637 integration tests passing across 52 test files (includes 18 plugin-specific tests)
Lint, format, typecheck, and build all clean

Test Plan

🐑 Built with Shep.bot

github-actions · 2026-04-14T06:44:55Z

🔒 Security Issues Detected

Scanner	Status	Details
Gitleaks	❌ Failed	Secret detection in git history
Semgrep	✅ Pass	SAST for TypeScript/JavaScript

⚠️ Please review the failed checks above before merging.

_{🤖 Generated by CI Security Scan | View Details}

github-actions · 2026-04-14T07:01:31Z

Dev Release Published

Artifact	Version	Install
npm	`1.183.0-pr555.262baa8`	`npm install -g @shepai/cli@1.183.0-pr555.262baa8`

_{Published from commit 3cb34fc | View CI}

github-actions · 2026-04-14T07:15:36Z

Dev Release Published

Artifact	Version	Install
npm	`1.183.0-pr555.e53ab0e`	`npm install -g @shepai/cli@1.183.0-pr555.e53ab0e`

_{Published from commit 393f2da | View CI}

…stem Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…ugin system Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…l plugin system Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Define Plugin entity, ToolGroup model, and three enums (PluginType, PluginTransport, PluginHealthStatus) in TypeSpec. Add optional activePlugins field to Feature entity for per-feature plugin activation overrides. All generated types compile cleanly with zero test breakage. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…nd repository Introduces the complete persistence foundation for the AI tool plugin system: - Migration 060: CREATE TABLE plugins with all columns matching the Plugin entity, including JSON columns for arrays (server_args, required_env_vars, tool_groups, active_tool_groups) and a UNIQUE index on the name column - Migration 061: ALTER TABLE features ADD COLUMN active_plugins TEXT for per-feature plugin activation overrides (JSON-serialized Record<string, boolean>) - PluginRow mapper: toDatabase/fromDatabase with camelCase/snake_case conversion, JSON serialization for array fields, boolean-to-integer mapping, and Date-to-unix millisecond conversion - IPluginRepository interface: CRUD port (create, findById, findByName, list, update, delete) in application/ports/output/repositories - SQLitePluginRepository: Full implementation with prepared statements - Feature mapper/repository extension: activePlugins field added to FeatureRow, toDatabase, fromDatabase, INSERT column list, and UPDATE SET clause - Comprehensive test coverage: 26 mapper unit tests, 18 repository integration tests, 5 feature mapper activePlugins tests, 4 feature repository activePlugins integration tests — all passing Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Add IMcpServerManager and IPluginHealthChecker port interfaces for MCP server lifecycle and plugin health verification. Create curated plugin catalog with MemPalace, Token Optimizer, and Ruflo entries. Implement seven plugin use cases: GetPluginCatalog, AddPlugin, RemovePlugin, ListPlugins, EnablePlugin, DisablePlugin, and ConfigurePlugin. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…case Implement PluginHealthCheckerService with multi-tier health checks: runtime detection via which/where, env var validation. Add CheckPluginHealthUseCase that runs health checks and persists updated status to the plugin repository. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Wire up IPluginRepository, IPluginHealthChecker, IMcpServerManager (no-op placeholder), 8 plugin use cases, and their string-token aliases for web route resolution. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…ycle McpServerManagerService replaces the no-op placeholder with real child_process.spawn() management. Features: per-feature server start/stop, reference counting for shared servers across concurrent features, temp .mcp.json config file generation, SIGTERM cleanup, and explicit env var passing (PATH + required vars only). Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

New optional mcpConfigPath field on AgentExecutionOptions carries the path to a per-feature .mcp.json temp file through the agent-agnostic interface. Each executor translates this to its own MCP config flag. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

ClaudeCodeExecutorService.buildArgs() now adds --mcp-config <path> when options.mcpConfigPath is set. This tells Claude Code to load plugin MCP servers from the generated per-feature temp file. Works alongside existing --strict-mcp-config (disableMcp) flag. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…ptions builder Wire mcpConfigPath through the feature agent graph state annotation and buildExecutorOptions so plugin MCP server config is forwarded to the agent executor. Update test state fixtures to include the new channel. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…t worker Start enabled MCP plugin servers before graph invocation and pass the generated mcpConfigPath into graph state. Stop servers in the finally block for cleanup. Degrades gracefully if plugin startup fails. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Add shep plugin {add,remove,list,enable,disable,configure,status,catalog} CLI commands following the settings command group pattern. Each subcommand resolves its use case from the DI container and provides user-friendly output with colored status indicators and table formatting. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

…ure toggles - Add 7 server actions for plugin CRUD operations (list, add, remove, toggle, configure, health check, catalog) - Add PluginList component with health status badges and enable/disable toggles - Add PluginCatalog browser component with install buttons - Add /plugins page with tabbed Installed/Catalog views - Add plugins navigation item to app sidebar with i18n support - Add per-feature plugin activation toggles to the create feature drawer - Wire activePlugins through CreateDrawerClient, server action, and use case layers Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

Rewrote docs(specs) research commit subject from 74 to 54 characters to pass commitlint subject-max-length rule. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

github-actions · 2026-04-14T08:29:22Z

Dev Release Published

Artifact	Version	Install
npm	`1.184.0-pr555.4b88627`	`npm install -g @shepai/cli@1.184.0-pr555.4b88627`

_{Published from commit ce5384b | View CI}

arielshad force-pushed the feat/ai-tool-plugin-system branch from 3cb34fc to 393f2da Compare April 14, 2026 07:04

arielshad and others added 23 commits April 14, 2026 11:05

docs(specs): analyze repository and define spec for ai tool plugin sy…

343857d

…stem Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

docs(specs): define requirements and product questions for ai tool pl…

2a7ba14

…ugin system Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

docs(specs): research technical decisions for ai tool plugin system

4b9dca7

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

docs(specs): create implementation plan and task breakdown for ai too…

aae62ff

…l plugin system Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

test(cli): add plugin command group unit tests

72c26a2

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

chore(specs): capture evidence for ai tool plugin system feature

7f328ef

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

chore(specs): recapture evidence screenshots for ai tool plugin system

ec2da4f

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

chore(specs): recapture evidence for ai tool plugin system

063d195

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

chore(specs): add feature tracking yaml for ai tool plugin system

ada3e8a

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

fix(ci): attempt 1/10 — add gitleaks ignore for mock tokens

6b67604

Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

fix(ci): attempt 2/10 — shorten commit subject exceeding 72 char limit

ce5384b

Rewrote docs(specs) research commit subject from 74 to 54 characters to pass commitlint subject-max-length rule. Co-Authored-By: Shep Bot <shep-agent@users.noreply.github.com>

arielshad force-pushed the feat/ai-tool-plugin-system branch from 393f2da to ce5384b Compare April 14, 2026 08:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(domain): add pluggable ai tool system with mcp server lifecycle management#555

feat(domain): add pluggable ai tool system with mcp server lifecycle management#555
arielshad wants to merge 23 commits intomainfrom
feat/ai-tool-plugin-system

arielshad commented Apr 14, 2026

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

arielshad commented Apr 14, 2026

Summary

Evidence

Web UI - Installed Plugins Tab (empty state)

Web UI - Plugin Catalog Browser

Web UI - Sidebar Navigation with Plugins

Web UI - Create Feature Drawer with Plugin Toggles

Test Results

Test Plan

Uh oh!

github-actions Bot commented Apr 14, 2026

🔒 Security Issues Detected

Uh oh!

github-actions Bot commented Apr 14, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Apr 14, 2026

Dev Release Published

Uh oh!

github-actions Bot commented Apr 14, 2026

Dev Release Published

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant