@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.
- package/.agents/agents/api-engineer.md +67 -0
- package/.agents/agents/failure-analyst.md +75 -0
- package/.agents/agents/live-explorer.md +70 -0
- package/.agents/agents/orchestrator.md +104 -0
- package/.agents/agents/perf-engineer.md +74 -0
- package/.agents/agents/pom-crafter.md +112 -0
- package/.agents/agents/quality-gatekeeper.md +87 -0
- package/.agents/agents/test-designer.md +73 -0
- package/.agents/agents/test-runner.md +67 -0
- package/.agents/rules/author-integrity-guard.md +33 -0
- package/.agents/rules/communication-style.md +18 -0
- package/.agents/rules/context-engineering.md +37 -0
- package/.agents/rules/git-push-protocol.md +33 -0
- package/.agents/rules/graphify.md +14 -0
- package/.agents/rules/lessons-learned.md +25 -0
- package/.agents/rules/mandatory-playwright-live.md +25 -0
- package/.agents/rules/mobile_appium_rules.md +43 -0
- package/.agents/rules/performance_testing_rules.md +35 -0
- package/.agents/rules/skill-precedence.md +29 -0
- package/.agents/rules/systematic-debugging.md +36 -0
- package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
- package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
- package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
- package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
- package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
- package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
- package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
- package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
- package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
- package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
- package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
- package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
- package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
- package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
- package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
- package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
- package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
- package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
- package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
- package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
- package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
- package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
- package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
- package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
- package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
- package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
- package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
- package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
- package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
- package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
- package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
- package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
- package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
- package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
- package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
- package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
- package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
- package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
- package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
- package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
- package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
- package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
- package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
- package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
- package/.agents/skills/github-actions-templates/SKILL.md +77 -0
- package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
- package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
- package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
- package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
- package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
- package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
- package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
- package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
- package/.agents/skills/lam-script-generator/SKILL.md +123 -0
- package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
- package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
- package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
- package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
- package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
- package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
- package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
- package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
- package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
- package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
- package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
- package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
- package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
- package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
- package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
- package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
- package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
- package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
- package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
- package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
- package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
- package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
- package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
- package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
- package/.agents/skills/qa-memory-os/SKILL.md +80 -0
- package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
- package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
- package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
- package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
- package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
- package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
- package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
- package/.agents/skills/review-spec/SKILL.md +60 -0
- package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
- package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
- package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
- package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
- package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
- package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
- package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
- package/.agents/skills/self-healing-locator/SKILL.md +86 -0
- package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
- package/.agents/skills/senior-code-review/SKILL.md +108 -0
- package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
- package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
- package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
- package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
- package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
- package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
- package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
- package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
- package/.agents/skills/systematic-debugging/SKILL.md +100 -0
- package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
- package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
- package/.agents/skills/test-driven-development/SKILL.md +114 -0
- package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
- package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
- package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
- package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
- package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
- package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
- package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
- package/.agents/skills/verification-before-completion/SKILL.md +100 -0
- package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
- package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
- package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
- package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
- package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
- package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
- package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
- package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
- package/.agents/templates/completion_report.md +57 -0
- package/.agents/workflows/analyze_requirement_document.md +18 -0
- package/.agents/workflows/export_testcases_excel.md +32 -0
- package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
- package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
- package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
- package/.agents/workflows/generate_requirements_from_website.md +25 -0
- package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
- package/.agents/workflows/graphify.md +10 -0
- package/.agents/workflows/test-impact.md +15 -0
- package/.agents/workflows/verify.md +34 -0
- package/.cursor/rules/agents.mdc +16 -0
- package/.cursor/rules/language.mdc +7 -0
- package/.cursor/rules/synapse-qa.mdc +24 -0
- package/.cursorrules +27 -0
- package/.dockerignore +53 -0
- package/.pre-commit-hooks.yaml +14 -0
- package/.windsurfrules +26 -0
- package/AGENTS.md +86 -0
- package/CLAUDE.md +54 -0
- package/Dockerfile +81 -0
- package/LICENSE +52 -0
- package/NOTICE +264 -0
- package/README.en.md +171 -0
- package/README.md +170 -2
- package/action.yml +51 -0
- package/agentskills.json +16 -0
- package/bin/agent-qa.js +138 -0
- package/docker-compose.yml +74 -0
- package/docs/ARCHITECTURE.en.md +198 -0
- package/docs/ARCHITECTURE.md +199 -0
- package/docs/CI_CD_INTEGRATION.en.md +170 -0
- package/docs/CI_CD_INTEGRATION.md +170 -0
- package/docs/CLI_REFERENCE.en.md +174 -0
- package/docs/CLI_REFERENCE.md +176 -0
- package/docs/CONTRIBUTING.en.md +49 -0
- package/docs/CONTRIBUTING.md +49 -0
- package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
- package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
- package/docs/QUALITY_GATES.en.md +118 -0
- package/docs/QUALITY_GATES.md +118 -0
- package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
- package/docs/TOOL_CATALOG.md +129 -0
- package/docs/adopted-ecosystem-tools.md +96 -0
- package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
- package/docs/research/agent_skill_training_analysis.md +1358 -0
- package/docs/schemas/synapse.config.schema.json +86 -0
- package/package.json +94 -4
- package/plugin.json +31 -0
- package/scripts/generate_skill_examples.py +244 -0
- package/scripts/install.ps1 +112 -0
- package/scripts/install_global_plugin.ps1 +94 -0
- package/scripts/install_global_plugin.sh +49 -0
- package/scripts/lint_skills.ps1 +57 -0
- package/scripts/package_dist.py +337 -0
- package/scripts/setup.sh +59 -0
- package/scripts/update_hub.ps1 +19 -0
- package/scripts/update_hub.sh +15 -0
- package/skills_manifest.json +854 -0
- package/synapse.config.json +31 -0
- package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
- package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
- package/templates/ai_bridges/CLAUDE.md +54 -0
- package/templates/ai_bridges/copilot-instructions.md +20 -0
- package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
- package/templates/ai_bridges/windsurfrules +26 -0
- package/templates/ci/github-actions-synapse.yml +95 -0
- package/templates/ci/gitlab-ci-synapse.yml +16 -0
- package/templates/ui/index.html +1069 -0
- package/templates/welcome.html.tmpl +2074 -0
- package/tools/.infer_baseline.json +30 -0
- package/tools/TOOLS_RUNBOOK.md +1553 -0
- package/tools/TOOL_CATALOG.json +1769 -0
- package/tools/__init__.py +43 -0
- package/tools/_openapi_parser.py +158 -0
- package/tools/agent_canary.py +525 -0
- package/tools/agentless_patcher.py +417 -0
- package/tools/analyze_project.py +262 -0
- package/tools/api_drift_sentinel.py +208 -0
- package/tools/api_fuzzer.py +762 -0
- package/tools/author_integrity.py +190 -0
- package/tools/auto_heal.py +271 -0
- package/tools/auto_heal_reflexion.py +532 -0
- package/tools/autogen_qa_broker.py +844 -0
- package/tools/benchmark_swarm_context.py +394 -0
- package/tools/browser_helpers.js +746 -0
- package/tools/browsergym_eval.py +236 -0
- package/tools/bug_reporter.py +252 -0
- package/tools/bump_version.py +423 -0
- package/tools/cache_resolver.py +1214 -0
- package/tools/check_env.py +426 -0
- package/tools/check_version_sync.py +256 -0
- package/tools/ci_healing_hook.py +126 -0
- package/tools/cli.py +1598 -0
- package/tools/config_decoupler.py +253 -0
- package/tools/contract_validator.py +141 -0
- package/tools/core/__init__.py +70 -0
- package/tools/core/adapters.py +431 -0
- package/tools/core/circuit_breaker.py +263 -0
- package/tools/core/cli_runtime.py +66 -0
- package/tools/core/file_lock.py +159 -0
- package/tools/core/i18n.py +394 -0
- package/tools/core/memory_bus.py +905 -0
- package/tools/core/process_supervisor.py +332 -0
- package/tools/core/telemetry.py +329 -0
- package/tools/count_tokens.py +1267 -0
- package/tools/create_mock_docx.py +104 -0
- package/tools/dashboard_generator.py +2403 -0
- package/tools/db_sandbox.py +675 -0
- package/tools/debt_harvester.py +237 -0
- package/tools/distill_log.py +161 -0
- package/tools/dspy_qa_signatures.py +356 -0
- package/tools/e2e_flow_prober.py +132 -0
- package/tools/export_postman_collection.py +945 -0
- package/tools/flaky_detector.py +389 -0
- package/tools/fsm_enforcer.py +450 -0
- package/tools/fsm_middleware.py +401 -0
- package/tools/fuzz_payloads.py +197 -0
- package/tools/generate_allure_report.py +88 -0
- package/tools/generate_api_matrix.py +193 -0
- package/tools/generate_jmx_plan.py +1322 -0
- package/tools/generate_sbom.py +252 -0
- package/tools/generate_tc_from_story.py +203 -0
- package/tools/generate_test_reports.py +133 -0
- package/tools/generate_tool_catalog.py +482 -0
- package/tools/gherkin_suite.py +758 -0
- package/tools/git_pre_commit_guard.py +298 -0
- package/tools/goldfish_review.py +366 -0
- package/tools/heal/__init__.py +28 -0
- package/tools/heal_pr_automator.py +220 -0
- package/tools/heuristic_locator_matcher.py +351 -0
- package/tools/hub_publisher.py +623 -0
- package/tools/humanize_linter.py +438 -0
- package/tools/infer_linter.py +977 -0
- package/tools/init_config.py +306 -0
- package/tools/interview_story.py +116 -0
- package/tools/jira_sync.py +566 -0
- package/tools/jtl_analyzer.py +474 -0
- package/tools/lint/__init__.py +30 -0
- package/tools/lint_ai_docs.py +374 -0
- package/tools/lookup_tc.py +165 -0
- package/tools/lookup_xpath.py +167 -0
- package/tools/matrix_sharder.py +148 -0
- package/tools/mcp/__init__.py +18 -0
- package/tools/mcp_docx_server.ps1 +13 -0
- package/tools/mcp_docx_server.py +851 -0
- package/tools/mcp_excel_server.ps1 +13 -0
- package/tools/mcp_excel_server.py +441 -0
- package/tools/mcp_server.py +725 -0
- package/tools/md_to_xlsx.py +327 -0
- package/tools/micro_mutator.py +887 -0
- package/tools/mipro_assertion_tuner.py +210 -0
- package/tools/network_mock_shield.py +311 -0
- package/tools/newman_analyzer.py +384 -0
- package/tools/omni_emitter.py +579 -0
- package/tools/omni_parser.py +450 -0
- package/tools/omni_transpiler.py +168 -0
- package/tools/openxml_guard.py +438 -0
- package/tools/output_formatter.py +182 -0
- package/tools/package_release.py +325 -0
- package/tools/perf/__init__.py +24 -0
- package/tools/pinpoint_failure.py +190 -0
- package/tools/project_state.py +171 -0
- package/tools/qa_event_stream.py +358 -0
- package/tools/repo_map.py +346 -0
- package/tools/report/__init__.py +32 -0
- package/tools/reversible_sandbox.py +344 -0
- package/tools/safety_firewall.py +437 -0
- package/tools/security_coverage_ledger.py +538 -0
- package/tools/security_scanner.py +229 -0
- package/tools/senior_code_review.py +393 -0
- package/tools/setup_project.py +770 -0
- package/tools/skill_collision_guard.py +304 -0
- package/tools/skill_profiles.py +217 -0
- package/tools/skill_vault.py +481 -0
- package/tools/skillspector.py +1278 -0
- package/tools/smart_visual_masker.py +132 -0
- package/tools/spec_drift_sentinel.py +438 -0
- package/tools/swe_qa_aci.py +369 -0
- package/tools/synapse_observer.py +485 -0
- package/tools/synapse_qa_bench.py +190 -0
- package/tools/sync_agent_rules.py +274 -0
- package/tools/telemetry_correlator.py +397 -0
- package/tools/template_excel_exporter.py +514 -0
- package/tools/templates/jmeter-distributed/README.md +54 -0
- package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
- package/tools/test_impact.py +419 -0
- package/tools/test_memory_os.py +462 -0
- package/tools/textgrad_mutation_optimizer.py +237 -0
- package/tools/tms_sync_bridge.py +834 -0
- package/tools/tot_exploratory_tester.py +239 -0
- package/tools/trace_data_flow.py +240 -0
- package/tools/traffic_session_converter.py +256 -0
- package/tools/trend_analytics.py +314 -0
- package/tools/ui_server.py +401 -0
- package/tools/universal_ir.py +488 -0
- package/tools/update_sentinel.py +383 -0
- package/tools/validate_groovy_scripts.py +173 -0
- package/tools/verify_all.py +1271 -0
- package/tools/visual_diff_canvas.py +143 -0
- package/tools/visual_som_helper.py +550 -0
- package/tools/watch_mode.py +308 -0
- package/tools/wcag_audit.py +239 -0
- 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\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()
|