Skip to content

FOUR-34384 Migrate ProcessMaker Core skills to Skills repository - #9162

Merged
caleeli merged 3 commits into
feature/FOUR-34328from
FOUR-34384
Nov 12, 2026
Merged

caleeli merged 3 commits into
feature/FOUR-34328from
FOUR-34384

Conversation

@devmiguelangel

@devmiguelangel devmiguelangel commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Issue & Reproduction Steps

Core still bundles 33 MCP skill markdown files and a system-skill catalog (McpSystemSkills) that the seeder writes into the mcp.skills setting. The same guidance now lives in the Skills repository (ProcessMaker/skills), which MCP clients install directly. Keeping both copies drifts, and the MCP server instructions still reference slugs that no longer resolve.

Solution

  • Delete ProcessMaker/Mcp/skills/*.md and ProcessMaker/Mcp/McpSystemSkills.php.
  • Rename McpSystemSkillsSeeder to McpSettingsSeeder. It creates the mcp.system_prompt and mcp.skills settings if missing, stops upserting system skills, and leaves custom skills untouched. DatabaseSeeder and 2026_11_06_143900_add_mcp_settings_menu use the new name.
  • Add upgrade 2026_11_11_190000_remove_mcp_system_skills, which removes stored entries with system: true, an id prefixed mcp-system-, or the legacy id skill-1793976475109-l6si55 from mcp.skills. Custom skills are kept, it is idempotent, and down() is a no-op.
  • Replace hard-coded Core slugs in the ScreenServer, ProcessServer, DataConnectorsServer, and FlowGenieServer instructions, the six affected tool descriptions, the ScreenConfigValidator warning, and ProcessPlanner with pointers to the matching pm4-* skills.
  • Rewrite the MCP tests: ProcessServerTest, DataConnectorsServerTest, and FlowGenieServerTest use custom scoped skills; McpSystemSkillsSeederTest is replaced by McpSettingsSeederTest; RemoveMcpSystemSkillsTest covers the purge.

Not changed: the system flag in McpGuidance.php and the McpSkills.vue UI still exist. They are now unused for built-in skills and can be removed in a follow-up.

How to Test

  1. Run php artisan test --filter='Mcp|RemoveMcpSystemSkills'.
  2. On an instance with the old system skills in mcp.skills, run php artisan migrate. Confirm that only custom skills remain in the mcp.skills setting.
  3. Run php artisan db:seed --class=Database\\Seeders\\McpSettingsSeeder twice. Confirm the settings exist once and custom skills are unchanged.
  4. Call get-mcp-guidance from an MCP client. Confirm the response lists only custom skills and the instructions point to the Skills repository.

Related Tickets & Packages

FOUR-34384
https://github.com/ProcessMaker/skills/pull/54

Code Review Checklist

  • I have pulled this code locally and tested it on my instance, along with any associated packages.
  • This code adheres to ProcessMaker Coding Guidelines.
  • This code includes a unit test or an E2E test that tests its functionality, or is covered by an existing test.
  • This solution fixes the bug reported in the original ticket.
  • This solution does not alter the expected output of a component in a way that would break existing Processes.
  • This solution does not implement any breaking changes that would invalidate documentation or cause existing Processes to fail.
  • This solution has been tested with enterprise packages that rely on its functionality and does not introduce bugs in those packages.
  • This code does not duplicate functionality that already exists in the framework or in ProcessMaker.
  • This ticket conforms to the PRD associated with this part of ProcessMaker.

ci:nayra:FOUR-34376

@cursor

cursor Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

PR Summary

Medium Risk
Upgrades purge built-in skills from settings and MCP instructions now depend on the external Skills repo—agents that only used get-mcp-skill for platform slugs will need the new install path until clients adopt it.

Overview
Built-in MCP skill content is removed from core — McpSystemSkills, all ProcessMaker/Mcp/skills/*.md files, and McpSystemSkillsSeeder are deleted. Fresh installs and seeding now use McpSettingsSeeder, which only ensures mcp.system_prompt and mcp.skills exist with an updated helper pointing agents to npx skills add processmaker/skills and pm4-* skills instead of seeding platform markdown into the database.

An upgrade 2026_11_11_190000_remove_mcp_system_skills strips stored system entries from mcp.skills (ids prefixed mcp-system-, system: true, or legacy skill-1793976475109-l6si55) while keeping tenant custom skills. DatabaseSeeder and the MCP settings menu migration call the new seeder.

MCP surfaces now reference the external repo — ScreenServer, ProcessServer, DataConnectorsServer, FlowGenieServer instructions, six tool descriptions, ScreenConfigValidator, and ProcessPlanner no longer cite local slugs like screen-creation-rules / process-creation-rules; they direct clients to pm4-screen, pm4-process, pm4-data-connector, pm4-collection, and pm4-flow-genie.

Tests are aligned with custom scoped skills only, plus new coverage for McpSettingsSeeder and the removal upgrade.

Reviewed by Cursor Bugbot for commit c5aff8d. Bugbot is set up for automated code reviews on this repo. Configure here.

@devmiguelangel devmiguelangel changed the title refactor(mcp): remove bundled MCP skills in favor of skills repo FOUR-34384 Migrate ProcessMaker Core skills to Skills repository Nov 12, 2026
@devmiguelangel devmiguelangel self-assigned this Nov 12, 2026
@caleeli
caleeli merged commit 55dc733 into feature/FOUR-34328 Nov 12, 2026
8 of 13 checks passed
@decisions-sonarqube

Copy link
Copy Markdown

Quality Gate passed Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarQube

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants