@teevee98/synapse-hub 0.0.0-stage → 3.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +171 -0
  190. package/README.md +170 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +198 -0
  196. package/docs/ARCHITECTURE.md +199 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +174 -0
  200. package/docs/CLI_REFERENCE.md +176 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +118 -0
  206. package/docs/QUALITY_GATES.md +118 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1358 -0
  212. package/docs/schemas/synapse.config.schema.json +86 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +31 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2074 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +262 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +190 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2403 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +306 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +725 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1271 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,851 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ Enterprise Cross-Platform MCP Docx Server (Zero-Dependency)
8
+ -----------------------------------------------------------
9
+ Implements Model Context Protocol (MCP) JSON-RPC 2.0 stdio server
10
+ for reading, inspecting, searching, and extracting text, tables,
11
+ and embedded screenshots/images from Microsoft Word (.docx) documents.
12
+
13
+ Works 100% offline with Python Standard Library (zipfile + xml.etree.ElementTree).
14
+ """
15
+
16
+ import os
17
+ import sys
18
+ import json
19
+ import zipfile
20
+ import re
21
+ import argparse
22
+ import xml.etree.ElementTree as ET
23
+ from pathlib import Path
24
+ from typing import Dict, Any, List, Optional, Union
25
+
26
+ try:
27
+ from openxml_guard import (
28
+ validate_openxml_path,
29
+ validate_output_path,
30
+ safe_open_zip,
31
+ safe_parse_xml,
32
+ jsonrpc_error_response,
33
+ PARSE_ERROR,
34
+ INVALID_REQUEST,
35
+ METHOD_NOT_FOUND,
36
+ INVALID_PARAMS,
37
+ INTERNAL_ERROR,
38
+ MAX_ZIP_ENTRIES
39
+ )
40
+ except ImportError:
41
+ from tools.openxml_guard import (
42
+ validate_openxml_path,
43
+ validate_output_path,
44
+ safe_open_zip,
45
+ safe_parse_xml,
46
+ jsonrpc_error_response,
47
+ PARSE_ERROR,
48
+ INVALID_REQUEST,
49
+ METHOD_NOT_FOUND,
50
+ INVALID_PARAMS,
51
+ INTERNAL_ERROR,
52
+ MAX_ZIP_ENTRIES
53
+ )
54
+
55
+ # Enforce UTF-8 stdio encoding for Windows/Linux/macOS console compatibility
56
+ if hasattr(sys.stdout, 'reconfigure'):
57
+ try:
58
+ sys.stdout.reconfigure(encoding='utf-8')
59
+ sys.stderr.reconfigure(encoding='utf-8')
60
+ except Exception:
61
+ pass
62
+
63
+ SERVER_VERSION = "3.8.3"
64
+ MAX_DOCX_SIZE = 50 * 1024 * 1024 # 50 MB
65
+ MAX_UNCOMPRESSED_SIZE = 200 * 1024 * 1024 # 200 MB
66
+ MAX_RATIO = 100 # 100:1 compression ratio limit
67
+
68
+ # Office Open XML Namespaces for WordprocessingML
69
+ NS_W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
70
+ NS_R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
71
+ NS_A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
72
+ NS_WP = "{http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing}"
73
+ NS_PIC = "{http://schemas.openxmlformats.org/drawingml/2006/picture}"
74
+ NS_V = "{urn:schemas-microsoft-com:vml}"
75
+ NS_CP = "{http://schemas.openxmlformats.org/package/2006/metadata/core-properties}"
76
+ NS_DC = "{http://purl.org/dc/elements/1.1/}"
77
+ NS_DCTERMS = "{http://purl.org/dc/terms/}"
78
+
79
+
80
+ def validate_docx_path(path: str, workspace_root: Optional[Union[str, Path]] = None) -> str:
81
+ """Validates that path is safe, does not resolve to sensitive system directories, and is a valid .docx file."""
82
+ target = validate_openxml_path(
83
+ path,
84
+ workspace_root=workspace_root,
85
+ allowed_extensions=('.docx',),
86
+ max_file_size=MAX_DOCX_SIZE
87
+ )
88
+ return str(target)
89
+
90
+
91
+ def get_docx_zip(docx_path: str) -> zipfile.ZipFile:
92
+ """Opens docx zip with zip-bomb safeguards."""
93
+ valid_path = validate_docx_path(docx_path)
94
+ return safe_open_zip(
95
+ valid_path,
96
+ max_entries=MAX_ZIP_ENTRIES,
97
+ max_uncompressed_size=MAX_UNCOMPRESSED_SIZE,
98
+ max_ratio=MAX_RATIO
99
+ )
100
+
101
+
102
+ def get_docx_relationships(z: zipfile.ZipFile) -> Dict[str, str]:
103
+ """Reads word/_rels/document.xml.rels and returns mapping of rId -> target media path."""
104
+ rels_map = {}
105
+ rels_entry = "word/_rels/document.xml.rels"
106
+ if rels_entry not in z.namelist():
107
+ return rels_map
108
+
109
+ try:
110
+ with z.open(rels_entry) as f:
111
+ tree = ET.parse(f)
112
+ root = tree.getroot()
113
+ for elem in root:
114
+ rid = elem.attrib.get("Id")
115
+ target = elem.attrib.get("Target")
116
+ if rid and target:
117
+ # Normalize target to relative zip path inside word/
118
+ if not target.startswith("word/") and not target.startswith("/"):
119
+ norm_target = f"word/{target}" if not target.startswith("media/") else f"word/{target}"
120
+ else:
121
+ norm_target = target.lstrip("/")
122
+ rels_map[rid] = norm_target
123
+ except (ET.ParseError, KeyError, UnicodeDecodeError, ValueError) as err:
124
+ sys.stderr.write(f"Warning: Failed to parse relationships: {err}\n")
125
+
126
+ return rels_map
127
+
128
+
129
+ def get_docx_metadata(z: zipfile.ZipFile) -> Dict[str, str]:
130
+ """Extracts core document metadata from docProps/core.xml."""
131
+ meta = {"title": "", "creator": "", "created": "", "modified": "", "description": ""}
132
+ core_entry = "docProps/core.xml"
133
+ if core_entry not in z.namelist():
134
+ return meta
135
+
136
+ try:
137
+ with z.open(core_entry) as f:
138
+ tree = ET.parse(f)
139
+ root = tree.getroot()
140
+ for child in root:
141
+ tag = child.tag
142
+ text = (child.text or "").strip()
143
+ if tag == f"{NS_DC}title":
144
+ meta["title"] = text
145
+ elif tag == f"{NS_DC}creator":
146
+ meta["creator"] = text
147
+ elif tag == f"{NS_DC}description":
148
+ meta["description"] = text
149
+ elif tag == f"{NS_DCTERMS}created":
150
+ meta["created"] = text
151
+ elif tag == f"{NS_DCTERMS}modified":
152
+ meta["modified"] = text
153
+ except (ET.ParseError, KeyError, UnicodeDecodeError, ValueError) as err:
154
+ sys.stderr.write(f"Warning: Failed to parse metadata: {err}\n")
155
+
156
+ return meta
157
+
158
+
159
+ def _extract_heading_level(p_elem: ET.Element) -> Optional[int]:
160
+ """Determines heading level (1 to 6) from paragraph style if present."""
161
+ p_pr = p_elem.find(f"{NS_W}pPr")
162
+ if p_pr is None:
163
+ return None
164
+
165
+ p_style = p_pr.find(f"{NS_W}pStyle")
166
+ if p_style is None:
167
+ return None
168
+
169
+ val = p_style.attrib.get(f"{NS_W}val", "")
170
+ val_clean = val.lower().replace(" ", "").replace("_", "")
171
+
172
+ # Match Heading1, Heading2, H1, H2, Heading 1, etc.
173
+ m = re.search(r'(?:heading|tieude|h)([1-6])', val_clean)
174
+ if m:
175
+ return int(m.group(1))
176
+
177
+ if val_clean in ("title", "tieude"):
178
+ return 1
179
+ if val_clean in ("subtitle", "phutieude"):
180
+ return 2
181
+
182
+ # Check for direct numeric style (e.g. style="1" or "2")
183
+ if val.isdigit() and 1 <= int(val) <= 6:
184
+ return int(val)
185
+
186
+ return None
187
+
188
+
189
+ def _extract_paragraph_text(p_elem: ET.Element) -> str:
190
+ """Concatenates text runs inside a paragraph."""
191
+ parts = []
192
+ for node in p_elem.iter(f"{NS_W}t"):
193
+ if node.text:
194
+ parts.append(node.text)
195
+ return "".join(parts).strip()
196
+
197
+
198
+ def _find_images_in_paragraph(p_elem: ET.Element, rels_map: Dict[str, str]) -> List[Dict[str, str]]:
199
+ """Identifies image drawings and blip embeds inside a paragraph."""
200
+ images = []
201
+
202
+ # 1. Search drawing elements
203
+ for drawing in p_elem.iter(f"{NS_W}drawing"):
204
+ doc_pr = drawing.find(f".//{NS_WP}docPr")
205
+ name = doc_pr.attrib.get("name", "") if doc_pr is not None else ""
206
+ descr = doc_pr.attrib.get("descr", "") if doc_pr is not None else ""
207
+
208
+ for blip in drawing.iter(f"{NS_A}blip"):
209
+ embed_id = blip.attrib.get(f"{NS_R}embed") or blip.attrib.get(f"{NS_R}link")
210
+ if embed_id and embed_id in rels_map:
211
+ target_zip_path = rels_map[embed_id]
212
+ images.append({
213
+ "r_id": embed_id,
214
+ "zip_path": target_zip_path,
215
+ "filename": os.path.basename(target_zip_path),
216
+ "caption": descr or name or os.path.basename(target_zip_path),
217
+ })
218
+
219
+ # 2. Search legacy VML pict elements
220
+ for pict in p_elem.iter(f"{NS_W}pict"):
221
+ for imagedata in pict.iter(f"{NS_V}imagedata"):
222
+ r_id = imagedata.attrib.get(f"{NS_R}id")
223
+ if r_id and r_id in rels_map:
224
+ target_zip_path = rels_map[r_id]
225
+ images.append({
226
+ "r_id": r_id,
227
+ "zip_path": target_zip_path,
228
+ "filename": os.path.basename(target_zip_path),
229
+ "caption": os.path.basename(target_zip_path),
230
+ })
231
+
232
+ return images
233
+
234
+
235
+ def _extract_table_matrix(tbl_elem: ET.Element) -> List[List[str]]:
236
+ """Extracts rows and cell text from a table element."""
237
+ matrix = []
238
+ for tr in tbl_elem.iter(f"{NS_W}tr"):
239
+ row = []
240
+ for tc in tr.iter(f"{NS_W}tc"):
241
+ cell_text_parts = []
242
+ for p in tc.iter(f"{NS_W}p"):
243
+ t = _extract_paragraph_text(p)
244
+ if t:
245
+ cell_text_parts.append(t)
246
+ row.append(" ".join(cell_text_parts))
247
+ if any(row):
248
+ matrix.append(row)
249
+ return matrix
250
+
251
+
252
+ def _table_to_markdown(matrix: List[List[str]]) -> str:
253
+ """Formats a 2D matrix into a clean Markdown table."""
254
+ if not matrix:
255
+ return ""
256
+
257
+ num_cols = max(len(row) for row in matrix)
258
+ if num_cols == 0:
259
+ return ""
260
+
261
+ # Normalize rows
262
+ norm_matrix = []
263
+ for r in matrix:
264
+ padded = r + [""] * (num_cols - len(r))
265
+ clean_row = [c.replace("\n", " ").replace("|", "\\|").strip() for c in padded]
266
+ norm_matrix.append(clean_row)
267
+
268
+ header = norm_matrix[0]
269
+ separator = ["---"] * num_cols
270
+ lines = [
271
+ "| " + " | ".join(header) + " |",
272
+ "| " + " | ".join(separator) + " |",
273
+ ]
274
+ for row in norm_matrix[1:]:
275
+ lines.append("| " + " | ".join(row) + " |")
276
+
277
+ return "\n".join(lines)
278
+
279
+
280
+ def inspect_docx(docx_path: str) -> Dict[str, Any]:
281
+ """Inspects docx structure, outline, headings, tables, and embedded images."""
282
+ with get_docx_zip(docx_path) as z:
283
+ metadata = get_docx_metadata(z)
284
+ rels_map = get_docx_relationships(z)
285
+
286
+ doc_entry = "word/document.xml"
287
+ if doc_entry not in z.namelist():
288
+ raise ValueError("Corrupt .docx: missing word/document.xml")
289
+
290
+ try:
291
+ with z.open(doc_entry) as f:
292
+ root = safe_parse_xml(f)
293
+ except ValueError as err:
294
+ raise ValueError(f"Corrupt .docx: {err}")
295
+
296
+ body = root.find(f"{NS_W}body")
297
+ if body is None:
298
+ raise ValueError("Corrupt .docx: missing <w:body> element")
299
+
300
+ headings = []
301
+ images_summary = []
302
+ total_paragraphs = 0
303
+ total_tables = 0
304
+ current_heading = "Document Root"
305
+
306
+ for elem in body:
307
+ if elem.tag == f"{NS_W}p":
308
+ total_paragraphs += 1
309
+ level = _extract_heading_level(elem)
310
+ text = _extract_paragraph_text(elem)
311
+ if level is not None and text:
312
+ current_heading = text
313
+ headings.append({"level": level, "title": text})
314
+
315
+ imgs = _find_images_in_paragraph(elem, rels_map)
316
+ for img in imgs:
317
+ images_summary.append({
318
+ "filename": img["filename"],
319
+ "caption": img["caption"],
320
+ "nearest_heading": current_heading,
321
+ "context_text": text[:120] if text else "",
322
+ })
323
+ elif elem.tag == f"{NS_W}tbl":
324
+ total_tables += 1
325
+
326
+ all_media_files = [n for n in z.namelist() if n.startswith("word/media/")]
327
+
328
+ return {
329
+ "file_name": os.path.basename(docx_path),
330
+ "metadata": metadata,
331
+ "counts": {
332
+ "total_paragraphs": total_paragraphs,
333
+ "total_headings": len(headings),
334
+ "total_tables": total_tables,
335
+ "embedded_images_in_body": len(images_summary),
336
+ "total_media_files_in_zip": len(all_media_files),
337
+ },
338
+ "outline": headings,
339
+ "images": images_summary,
340
+ }
341
+
342
+
343
+ def extract_docx_images(docx_path: str, output_dir: Optional[str] = None, max_images: int = 50) -> List[Dict[str, Any]]:
344
+ """Extracts embedded images/screenshots to a directory with security checks."""
345
+ valid_path = validate_docx_path(docx_path)
346
+ base_name = os.path.splitext(os.path.basename(valid_path))[0]
347
+
348
+ if not output_dir:
349
+ output_dir = os.path.join(os.getcwd(), "reports", "docx_media", base_name)
350
+
351
+ target_dir = validate_output_path(output_dir, create_parent=True)
352
+ target_dir.mkdir(parents=True, exist_ok=True)
353
+
354
+ extracted_records = []
355
+ with get_docx_zip(valid_path) as z:
356
+ rels_map = get_docx_relationships(z)
357
+
358
+ # Build mapping of image zip path to context
359
+ img_contexts = {}
360
+ current_heading = "Document Root"
361
+
362
+ doc_entry = "word/document.xml"
363
+ if doc_entry in z.namelist():
364
+ try:
365
+ with z.open(doc_entry) as f:
366
+ root = safe_parse_xml(f)
367
+ body = root.find(f"{NS_W}body")
368
+ if body is not None:
369
+ for elem in body:
370
+ if elem.tag == f"{NS_W}p":
371
+ level = _extract_heading_level(elem)
372
+ text = _extract_paragraph_text(elem)
373
+ if level is not None and text:
374
+ current_heading = text
375
+ imgs = _find_images_in_paragraph(elem, rels_map)
376
+ for img in imgs:
377
+ zp = img["zip_path"]
378
+ if zp not in img_contexts:
379
+ img_contexts[zp] = {
380
+ "caption": img["caption"],
381
+ "heading": current_heading,
382
+ "context": text,
383
+ }
384
+ except ValueError as err:
385
+ sys.stderr.write(f"Warning: Failed to parse image context: {err}\n")
386
+
387
+ media_entries = [n for n in z.namelist() if n.startswith("word/media/")]
388
+ for count, entry in enumerate(media_entries):
389
+ if count >= max_images:
390
+ break
391
+
392
+ filename = os.path.basename(entry.replace("\\", "/"))
393
+ dest_file = (target_dir / filename).resolve()
394
+
395
+ # Zip Slip / Path traversal safety check
396
+ if not dest_file.is_relative_to(target_dir):
397
+ continue
398
+
399
+ with z.open(entry) as src, open(dest_file, "wb") as dst:
400
+ data = src.read()
401
+ dst.write(data)
402
+
403
+ ctx = img_contexts.get(entry, {})
404
+ extracted_records.append({
405
+ "filename": filename,
406
+ "saved_path": str(dest_file),
407
+ "size_bytes": len(data),
408
+ "nearest_heading": ctx.get("heading", current_heading),
409
+ "caption": ctx.get("caption", filename),
410
+ "context_text": ctx.get("context", "")[:150],
411
+ })
412
+
413
+ return extracted_records
414
+
415
+
416
+ def read_docx_content(docx_path: str, heading_filter: Optional[str] = None, max_paragraphs: int = 250, extract_images_dir: Optional[str] = None) -> str:
417
+ """Reads docx paragraphs and tables formatted as clean Markdown."""
418
+ extracted_map = {}
419
+ if extract_images_dir:
420
+ records = extract_docx_images(docx_path, output_dir=extract_images_dir)
421
+ for r in records:
422
+ extracted_map[r["filename"]] = r["saved_path"]
423
+
424
+ with get_docx_zip(docx_path) as z:
425
+ rels_map = get_docx_relationships(z)
426
+ doc_entry = "word/document.xml"
427
+ if doc_entry not in z.namelist():
428
+ raise ValueError("Corrupt .docx: missing word/document.xml")
429
+ try:
430
+ with z.open(doc_entry) as f:
431
+ root = safe_parse_xml(f)
432
+ except ValueError as err:
433
+ raise ValueError(f"Corrupt .docx: {err}")
434
+
435
+ body = root.find(f"{NS_W}body")
436
+ if body is None:
437
+ return ""
438
+
439
+ output_lines = []
440
+ current_heading = ""
441
+ include_section = True if not heading_filter else False
442
+ p_count = 0
443
+
444
+ for elem in body:
445
+ if elem.tag == f"{NS_W}p":
446
+ level = _extract_heading_level(elem)
447
+ text = _extract_paragraph_text(elem)
448
+
449
+ if level is not None and text:
450
+ current_heading = text
451
+ if heading_filter:
452
+ include_section = heading_filter.lower() in text.lower()
453
+
454
+ if include_section:
455
+ prefix = "#" * max(1, min(6, level))
456
+ output_lines.append(f"\n{prefix} {text}\n")
457
+ continue
458
+
459
+ if not include_section:
460
+ continue
461
+
462
+ imgs = _find_images_in_paragraph(elem, rels_map)
463
+
464
+ if text:
465
+ output_lines.append(text)
466
+ p_count += 1
467
+
468
+ for img in imgs:
469
+ fname = img["filename"]
470
+ caption = img["caption"]
471
+ target_ref = extracted_map.get(fname, f"word/media/{fname}")
472
+ output_lines.append(f"\n![{caption}]({target_ref})\n")
473
+
474
+ if p_count >= max_paragraphs:
475
+ output_lines.append("\n\n*(Truncated: reached max_paragraphs limit)*")
476
+ break
477
+
478
+ elif elem.tag == f"{NS_W}tbl":
479
+ if not include_section:
480
+ continue
481
+ matrix = _extract_table_matrix(elem)
482
+ md_table = _table_to_markdown(matrix)
483
+ if md_table:
484
+ output_lines.append(f"\n{md_table}\n")
485
+
486
+ return "\n\n".join(output_lines).strip()
487
+
488
+
489
+ def read_docx_tables(docx_path: str, table_index: Optional[int] = None) -> List[Dict[str, Any]]:
490
+ """Extracts tables from a docx file as structured matrices and Markdown strings."""
491
+ tables = []
492
+ with get_docx_zip(docx_path) as z:
493
+ doc_entry = "word/document.xml"
494
+ if doc_entry not in z.namelist():
495
+ raise ValueError("Corrupt .docx: missing word/document.xml")
496
+ try:
497
+ with z.open(doc_entry) as f:
498
+ root = safe_parse_xml(f)
499
+ except ValueError as err:
500
+ raise ValueError(f"Corrupt .docx: {err}")
501
+ body = root.find(f"{NS_W}body")
502
+ if body is None:
503
+ return tables
504
+
505
+ idx = 0
506
+ for elem in body:
507
+ if elem.tag == f"{NS_W}tbl":
508
+ if table_index is not None and idx != table_index:
509
+ idx += 1
510
+ continue
511
+ matrix = _extract_table_matrix(elem)
512
+ md = _table_to_markdown(matrix)
513
+ tables.append({
514
+ "table_index": idx,
515
+ "rows": len(matrix),
516
+ "cols": len(matrix[0]) if matrix else 0,
517
+ "matrix": matrix,
518
+ "markdown": md,
519
+ })
520
+ idx += 1
521
+
522
+ return tables
523
+
524
+
525
+ def search_docx(docx_path: str, query: str, max_results: int = 10) -> List[Dict[str, Any]]:
526
+ """Searches for keyword or phrase across docx body paragraphs."""
527
+ if not query:
528
+ raise ValueError("Search query cannot be empty")
529
+
530
+ results = []
531
+ q_lower = query.lower()
532
+
533
+ with get_docx_zip(docx_path) as z:
534
+ rels_map = get_docx_relationships(z)
535
+ doc_entry = "word/document.xml"
536
+ if doc_entry not in z.namelist():
537
+ raise ValueError("Corrupt .docx: missing word/document.xml")
538
+ try:
539
+ with z.open(doc_entry) as f:
540
+ root = safe_parse_xml(f)
541
+ except ValueError as err:
542
+ raise ValueError(f"Corrupt .docx: {err}")
543
+ body = root.find(f"{NS_W}body")
544
+ if body is None:
545
+ return results
546
+
547
+ current_heading = "Document Root"
548
+ p_index = 0
549
+
550
+ for elem in body:
551
+ if elem.tag == f"{NS_W}p":
552
+ p_index += 1
553
+ level = _extract_heading_level(elem)
554
+ text = _extract_paragraph_text(elem)
555
+
556
+ if level is not None and text:
557
+ current_heading = text
558
+
559
+ if text and q_lower in text.lower():
560
+ imgs = _find_images_in_paragraph(elem, rels_map)
561
+ results.append({
562
+ "paragraph_index": p_index,
563
+ "heading": current_heading,
564
+ "matched_text": text,
565
+ "images": [img["filename"] for img in imgs],
566
+ })
567
+ if len(results) >= max_results:
568
+ break
569
+
570
+ return results
571
+
572
+
573
+ # ----------------------------------------------------------------------
574
+ # MCP Protocol Handlers & Manifest
575
+ # ----------------------------------------------------------------------
576
+
577
+ MCP_DOCX_MANIFEST = {
578
+ "tools": [
579
+ {
580
+ "name": "inspect_docx_structure",
581
+ "description": "Inspects Microsoft Word (.docx) document structure: outline, metadata, heading hierarchy, tables count, and embedded screenshots/images count in 0.05s.",
582
+ "inputSchema": {
583
+ "type": "object",
584
+ "properties": {
585
+ "file_path": {"type": "string", "description": "Absolute or relative path to the .docx file"}
586
+ },
587
+ "required": ["file_path"]
588
+ }
589
+ },
590
+ {
591
+ "name": "read_docx_content",
592
+ "description": "Reads docx document content converted cleanly to Markdown (headings, bullet points, tables, and image references). Supports section filtering to preserve AI context tokens.",
593
+ "inputSchema": {
594
+ "type": "object",
595
+ "properties": {
596
+ "file_path": {"type": "string", "description": "Path to the .docx file"},
597
+ "heading_filter": {"type": "string", "description": "Optional section heading to read (reads only this section)"},
598
+ "max_paragraphs": {"type": "integer", "description": "Maximum paragraphs to read (default: 200)"},
599
+ "extract_images_dir": {"type": "string", "description": "Optional directory to extract embedded images and embed local paths in markdown"}
600
+ },
601
+ "required": ["file_path"]
602
+ }
603
+ },
604
+ {
605
+ "name": "extract_docx_images",
606
+ "description": "Extracts embedded screenshots and images from Word (.docx) to a local directory with surrounding context for Multimodal AI Vision analysis.",
607
+ "inputSchema": {
608
+ "type": "object",
609
+ "properties": {
610
+ "file_path": {"type": "string", "description": "Path to the .docx file"},
611
+ "output_dir": {"type": "string", "description": "Target folder for extracted images (defaults to reports/docx_media/<doc_name>)"},
612
+ "max_images": {"type": "integer", "description": "Maximum images to extract (default: 50)"}
613
+ },
614
+ "required": ["file_path"]
615
+ }
616
+ },
617
+ {
618
+ "name": "read_docx_tables",
619
+ "description": "Extracts structured tables from a Word (.docx) document as JSON matrices and Markdown tables for test case requirements and matrix validation.",
620
+ "inputSchema": {
621
+ "type": "object",
622
+ "properties": {
623
+ "file_path": {"type": "string", "description": "Path to the .docx file"},
624
+ "table_index": {"type": "integer", "description": "Optional 0-based index of a specific table to extract"}
625
+ },
626
+ "required": ["file_path"]
627
+ }
628
+ },
629
+ {
630
+ "name": "search_docx",
631
+ "description": "Searches for keywords or requirements across a Word (.docx) document and returns matching paragraphs with their parent heading and nearby screenshots.",
632
+ "inputSchema": {
633
+ "type": "object",
634
+ "properties": {
635
+ "file_path": {"type": "string", "description": "Path to the .docx file"},
636
+ "query": {"type": "string", "description": "Keyword or text phrase to locate"},
637
+ "max_results": {"type": "integer", "description": "Maximum search matches (default: 10)"}
638
+ },
639
+ "required": ["file_path", "query"]
640
+ }
641
+ }
642
+ ]
643
+ }
644
+
645
+
646
+ def handle_tool_call(name: str, arguments: Dict[str, Any]) -> str:
647
+ """Executes Docx MCP tool functions."""
648
+ file_path = arguments.get("file_path", "")
649
+ if not file_path:
650
+ raise ValueError("Missing required 'file_path' argument")
651
+
652
+ if name == "inspect_docx_structure":
653
+ data = inspect_docx(file_path)
654
+ return json.dumps(data, ensure_ascii=False, indent=2)
655
+
656
+ elif name == "read_docx_content":
657
+ heading_filter = arguments.get("heading_filter")
658
+ max_paragraphs = int(arguments.get("max_paragraphs", 200))
659
+ extract_images_dir = arguments.get("extract_images_dir")
660
+ content = read_docx_content(file_path, heading_filter=heading_filter, max_paragraphs=max_paragraphs, extract_images_dir=extract_images_dir)
661
+ return content or "*(Document is empty or filtered section not found)*"
662
+
663
+ elif name == "extract_docx_images":
664
+ output_dir = arguments.get("output_dir")
665
+ max_images = int(arguments.get("max_images", 50))
666
+ images = extract_docx_images(file_path, output_dir=output_dir, max_images=max_images)
667
+ return json.dumps(images, ensure_ascii=False, indent=2)
668
+
669
+ elif name == "read_docx_tables":
670
+ table_idx = arguments.get("table_index")
671
+ if table_idx is not None:
672
+ table_idx = int(table_idx)
673
+ tables = read_docx_tables(file_path, table_index=table_idx)
674
+ return json.dumps(tables, ensure_ascii=False, indent=2)
675
+
676
+ elif name == "search_docx":
677
+ query = arguments.get("query", "")
678
+ max_results = int(arguments.get("max_results", 10))
679
+ results = search_docx(file_path, query=query, max_results=max_results)
680
+ return json.dumps(results, ensure_ascii=False, indent=2)
681
+
682
+ raise ValueError(f"Unknown MCP Docx tool: '{name}'")
683
+
684
+
685
+ MCP_DOCX_TOOL_NAMES = {t["name"] for t in MCP_DOCX_MANIFEST["tools"]}
686
+
687
+
688
+ def process_message(msg: Any) -> Optional[Dict[str, Any]]:
689
+ """JSON-RPC 2.0 message handler for Docx MCP."""
690
+ if not isinstance(msg, dict):
691
+ return jsonrpc_error_response(INVALID_REQUEST, "Invalid Request: message must be a JSON object", req_id=None)
692
+
693
+ msg_id = msg.get("id")
694
+
695
+ if msg.get("jsonrpc") != "2.0":
696
+ return jsonrpc_error_response(INVALID_REQUEST, "Invalid Request: 'jsonrpc' must be exactly '2.0'", req_id=msg_id)
697
+
698
+ method = msg.get("method")
699
+ if not isinstance(method, str) or not method:
700
+ return jsonrpc_error_response(INVALID_REQUEST, "Invalid Request: 'method' must be a non-empty string", req_id=msg_id)
701
+
702
+ # Notifications handling (no response per JSON-RPC 2.0 spec)
703
+ if method in ("notifications/initialized", "initialized") or method.startswith("notifications/"):
704
+ return None
705
+ if msg_id is None:
706
+ return None
707
+
708
+ if method == "initialize":
709
+ return {
710
+ "jsonrpc": "2.0",
711
+ "id": msg_id,
712
+ "result": {
713
+ "protocolVersion": "2024-11-05",
714
+ "capabilities": {"tools": {}},
715
+ "serverInfo": {"name": "synapse-mcp-docx", "version": SERVER_VERSION}
716
+ }
717
+ }
718
+ elif method == "ping":
719
+ return {"jsonrpc": "2.0", "id": msg_id, "result": {}}
720
+ elif method == "tools/list":
721
+ return {
722
+ "jsonrpc": "2.0",
723
+ "id": msg_id,
724
+ "result": MCP_DOCX_MANIFEST
725
+ }
726
+ elif method == "tools/call":
727
+ params = msg.get("params")
728
+ if not isinstance(params, dict):
729
+ return jsonrpc_error_response(INVALID_PARAMS, "Invalid params: 'params' must be a dictionary", req_id=msg_id)
730
+
731
+ tool_name = params.get("name")
732
+ if not isinstance(tool_name, str) or not tool_name:
733
+ return jsonrpc_error_response(INVALID_PARAMS, "Invalid params: tool 'name' must be a non-empty string", req_id=msg_id)
734
+
735
+ if tool_name not in MCP_DOCX_TOOL_NAMES:
736
+ return jsonrpc_error_response(METHOD_NOT_FOUND, f"Method not found: Unknown tool '{tool_name}'", req_id=msg_id)
737
+
738
+ args = params.get("arguments")
739
+ if args is None:
740
+ args = {}
741
+ if not isinstance(args, dict):
742
+ return jsonrpc_error_response(INVALID_PARAMS, "Invalid params: 'arguments' must be a dictionary", req_id=msg_id)
743
+
744
+ # Validate mandatory file_path argument
745
+ file_path = args.get("file_path")
746
+ if not file_path or not isinstance(file_path, str):
747
+ return jsonrpc_error_response(INVALID_PARAMS, "Invalid params: 'file_path' is required and must be a non-empty string", req_id=msg_id)
748
+
749
+ if tool_name == "search_docx":
750
+ query = args.get("query")
751
+ if not query or not isinstance(query, str):
752
+ return jsonrpc_error_response(INVALID_PARAMS, "Invalid params: 'query' is required and must be a non-empty string", req_id=msg_id)
753
+
754
+ try:
755
+ content = handle_tool_call(tool_name, args)
756
+ return {
757
+ "jsonrpc": "2.0",
758
+ "id": msg_id,
759
+ "result": {"content": [{"type": "text", "text": content}], "isError": False}
760
+ }
761
+ except PermissionError as e:
762
+ return jsonrpc_error_response(INVALID_PARAMS, f"Invalid params (traversal or permission denied): {e}", req_id=msg_id)
763
+ except (ValueError, FileNotFoundError) as e:
764
+ return {
765
+ "jsonrpc": "2.0",
766
+ "id": msg_id,
767
+ "result": {"content": [{"type": "text", "text": f"Error: {e}"}], "isError": True}
768
+ }
769
+ except Exception as e:
770
+ return jsonrpc_error_response(INTERNAL_ERROR, f"Internal error: {e}", req_id=msg_id)
771
+
772
+ return jsonrpc_error_response(METHOD_NOT_FOUND, f"Method not found: '{method}'", req_id=msg_id)
773
+
774
+
775
+ def run_stdio_server():
776
+ """Runs standard JSON-RPC 2.0 stdio server loop."""
777
+ for line in sys.stdin:
778
+ line = line.strip()
779
+ if not line:
780
+ continue
781
+ req_id = None
782
+ try:
783
+ try:
784
+ req = json.loads(line)
785
+ if isinstance(req, dict):
786
+ req_id = req.get("id")
787
+ except Exception as e:
788
+ err_resp = jsonrpc_error_response(PARSE_ERROR, f"Parse error: {e}", req_id=None)
789
+ sys.stdout.write(json.dumps(err_resp) + "\n")
790
+ sys.stdout.flush()
791
+ continue
792
+
793
+ resp = process_message(req)
794
+ if resp is not None:
795
+ sys.stdout.write(json.dumps(resp) + "\n")
796
+ sys.stdout.flush()
797
+ except Exception as e:
798
+ err_resp = jsonrpc_error_response(INTERNAL_ERROR, f"Internal error: {e}", req_id=req_id)
799
+ sys.stdout.write(json.dumps(err_resp) + "\n")
800
+ sys.stdout.flush()
801
+
802
+
803
+ def main():
804
+ """CLI dispatcher and stdio server entry point."""
805
+ parser = argparse.ArgumentParser(description="Synapse Hub MCP Microsoft Word (.docx) Inspection & Extraction Server")
806
+ parser.add_argument("command", nargs="?", default="mcp", choices=["mcp", "inspect", "read", "extract-images", "tables", "search"], help="Operation to perform (default: mcp)")
807
+ parser.add_argument("file_path", nargs="?", help="Path to .docx document")
808
+ parser.add_argument("--heading", help="Filter by section heading")
809
+ parser.add_argument("--out-dir", help="Output directory for extracted images")
810
+ parser.add_argument("--query", "-q", help="Search query string")
811
+ parser.add_argument("--max", type=int, default=50, help="Maximum items/paragraphs/images to process")
812
+ parser.add_argument("--index", type=int, help="Table index to read")
813
+
814
+ args = parser.parse_args()
815
+
816
+ if args.command == "mcp" and not args.file_path:
817
+ run_stdio_server()
818
+ return
819
+
820
+ if not args.file_path:
821
+ parser.print_help()
822
+ sys.exit(1)
823
+
824
+ try:
825
+ if args.command == "inspect":
826
+ data = inspect_docx(args.file_path)
827
+ print(json.dumps(data, ensure_ascii=False, indent=2))
828
+ elif args.command == "read":
829
+ content = read_docx_content(args.file_path, heading_filter=args.heading, max_paragraphs=args.max, extract_images_dir=args.out_dir)
830
+ print(content)
831
+ elif args.command == "extract-images":
832
+ records = extract_docx_images(args.file_path, output_dir=args.out_dir, max_images=args.max)
833
+ print(f"Extracted {len(records)} images:")
834
+ for r in records:
835
+ print(f" • {r['filename']} ({r['size_bytes']} bytes) -> {r['saved_path']} [Section: {r['nearest_heading']}]")
836
+ elif args.command == "tables":
837
+ tables = read_docx_tables(args.file_path, table_index=args.index)
838
+ print(json.dumps(tables, ensure_ascii=False, indent=2))
839
+ elif args.command == "search":
840
+ if not args.query:
841
+ print("Error: --query is required for search command", file=sys.stderr)
842
+ sys.exit(1)
843
+ results = search_docx(args.file_path, query=args.query, max_results=args.max)
844
+ print(json.dumps(results, ensure_ascii=False, indent=2))
845
+ except Exception as e:
846
+ print(f"Error: {e}", file=sys.stderr)
847
+ sys.exit(1)
848
+
849
+
850
+ if __name__ == "__main__":
851
+ main()