atengk-mcp-server-reverse 1.0.0__tar.gz

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 (86) hide show
  1. atengk_mcp_server_reverse-1.0.0/.cliff.toml +57 -0
  2. atengk_mcp_server_reverse-1.0.0/.dockerignore +78 -0
  3. atengk_mcp_server_reverse-1.0.0/.editorconfig +24 -0
  4. atengk_mcp_server_reverse-1.0.0/.gitattributes +44 -0
  5. atengk_mcp_server_reverse-1.0.0/.githooks/commit-msg +65 -0
  6. atengk_mcp_server_reverse-1.0.0/.github/CODEOWNERS +12 -0
  7. atengk_mcp_server_reverse-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md +30 -0
  8. atengk_mcp_server_reverse-1.0.0/.github/ISSUE_TEMPLATE/config.yml +16 -0
  9. atengk_mcp_server_reverse-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md +19 -0
  10. atengk_mcp_server_reverse-1.0.0/.github/PULL_REQUEST_TEMPLATE.md +25 -0
  11. atengk_mcp_server_reverse-1.0.0/.github/dependabot.yml +63 -0
  12. atengk_mcp_server_reverse-1.0.0/.github/workflows/ci.yml +111 -0
  13. atengk_mcp_server_reverse-1.0.0/.github/workflows/docker.yml +101 -0
  14. atengk_mcp_server_reverse-1.0.0/.github/workflows/publish.yml +78 -0
  15. atengk_mcp_server_reverse-1.0.0/.github/workflows/release.yml +148 -0
  16. atengk_mcp_server_reverse-1.0.0/.gitignore +97 -0
  17. atengk_mcp_server_reverse-1.0.0/AGENTS.md +15 -0
  18. atengk_mcp_server_reverse-1.0.0/CODE_OF_CONDUCT.md +58 -0
  19. atengk_mcp_server_reverse-1.0.0/CONTEXT.md +49 -0
  20. atengk_mcp_server_reverse-1.0.0/CONTRIBUTING.md +131 -0
  21. atengk_mcp_server_reverse-1.0.0/Dockerfile +55 -0
  22. atengk_mcp_server_reverse-1.0.0/LICENSE +201 -0
  23. atengk_mcp_server_reverse-1.0.0/PKG-INFO +406 -0
  24. atengk_mcp_server_reverse-1.0.0/README.md +177 -0
  25. atengk_mcp_server_reverse-1.0.0/SECURITY.md +38 -0
  26. atengk_mcp_server_reverse-1.0.0/docs/adr/0001-hybrid-static-analysis-engine.md +20 -0
  27. atengk_mcp_server_reverse-1.0.0/docs/adr/0002-lru-binary-session-and-pagination.md +17 -0
  28. atengk_mcp_server_reverse-1.0.0/docs/adr/0003-instruction-level-relative-xref-engine.md +21 -0
  29. atengk_mcp_server_reverse-1.0.0/docs/adr/0003-lazy-xref-index-and-arm64-sliding-window.md +23 -0
  30. atengk_mcp_server_reverse-1.0.0/docs/adr/0004-four-tier-tool-locator-and-health-probe.md +18 -0
  31. atengk_mcp_server_reverse-1.0.0/docs/agents/domain.md +52 -0
  32. atengk_mcp_server_reverse-1.0.0/docs/agents/issue-tracker.md +45 -0
  33. atengk_mcp_server_reverse-1.0.0/docs/agents/triage-labels.md +15 -0
  34. atengk_mcp_server_reverse-1.0.0/docs/spec.md +203 -0
  35. atengk_mcp_server_reverse-1.0.0/pyproject.toml +79 -0
  36. atengk_mcp_server_reverse-1.0.0/scripts/commit.sh +376 -0
  37. atengk_mcp_server_reverse-1.0.0/scripts/release.sh +377 -0
  38. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/__init__.py +9 -0
  39. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/__main__.py +12 -0
  40. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/cli.py +158 -0
  41. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/__init__.py +5 -0
  42. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/config.py +152 -0
  43. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/disasm.py +418 -0
  44. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/doctor.py +102 -0
  45. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/inspection.py +480 -0
  46. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/locator.py +262 -0
  47. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/memory.py +229 -0
  48. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/meta.py +65 -0
  49. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/models.py +385 -0
  50. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/parser.py +512 -0
  51. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/scanner.py +529 -0
  52. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/security.py +197 -0
  53. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/session.py +188 -0
  54. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/core/strings.py +293 -0
  55. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/server.py +460 -0
  56. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/__init__.py +5 -0
  57. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/capabilities.py +51 -0
  58. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/disasm.py +403 -0
  59. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/scanner.py +245 -0
  60. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/session.py +181 -0
  61. atengk_mcp_server_reverse-1.0.0/src/mcp_server_reverse/tools/symbols.py +225 -0
  62. atengk_mcp_server_reverse-1.0.0/tests/__init__.py +5 -0
  63. atengk_mcp_server_reverse-1.0.0/tests/fixtures/__init__.py +5 -0
  64. atengk_mcp_server_reverse-1.0.0/tests/fixtures/synthetic.py +469 -0
  65. atengk_mcp_server_reverse-1.0.0/tests/test_capabilities.py +69 -0
  66. atengk_mcp_server_reverse-1.0.0/tests/test_cli.py +72 -0
  67. atengk_mcp_server_reverse-1.0.0/tests/test_config.py +75 -0
  68. atengk_mcp_server_reverse-1.0.0/tests/test_disasm_and_xrefs.py +109 -0
  69. atengk_mcp_server_reverse-1.0.0/tests/test_disasm_tools.py +216 -0
  70. atengk_mcp_server_reverse-1.0.0/tests/test_doctor.py +61 -0
  71. atengk_mcp_server_reverse-1.0.0/tests/test_inspection.py +130 -0
  72. atengk_mcp_server_reverse-1.0.0/tests/test_locator.py +113 -0
  73. atengk_mcp_server_reverse-1.0.0/tests/test_memory.py +94 -0
  74. atengk_mcp_server_reverse-1.0.0/tests/test_models.py +70 -0
  75. atengk_mcp_server_reverse-1.0.0/tests/test_parser.py +70 -0
  76. atengk_mcp_server_reverse-1.0.0/tests/test_scanner.py +110 -0
  77. atengk_mcp_server_reverse-1.0.0/tests/test_scanner_tools.py +298 -0
  78. atengk_mcp_server_reverse-1.0.0/tests/test_security.py +87 -0
  79. atengk_mcp_server_reverse-1.0.0/tests/test_session.py +99 -0
  80. atengk_mcp_server_reverse-1.0.0/tests/test_session_tools.py +120 -0
  81. atengk_mcp_server_reverse-1.0.0/tests/test_string_models.py +44 -0
  82. atengk_mcp_server_reverse-1.0.0/tests/test_strings.py +141 -0
  83. atengk_mcp_server_reverse-1.0.0/tests/test_symbol_models.py +42 -0
  84. atengk_mcp_server_reverse-1.0.0/tests/test_symbol_tools.py +294 -0
  85. atengk_mcp_server_reverse-1.0.0/tests/test_synthetic.py +57 -0
  86. atengk_mcp_server_reverse-1.0.0/uv.lock +1277 -0
@@ -0,0 +1,57 @@
1
+ # ==============================================================================
2
+ # git-cliff 自动化变更日志配置
3
+ # 详见: https://git-cliff.org/docs/configuration
4
+ # ==============================================================================
5
+
6
+ [remote.github]
7
+ owner = "atengk"
8
+ repo = "mcp-server-reverse"
9
+
10
+ [changelog]
11
+ header = ""
12
+ body = """
13
+ {% for entry in commits | commit_groups(groups=commit_parsers_groups) %}
14
+ ### {{ entry.group | trim }}
15
+ {% for commit in entry.commits %}
16
+ - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}{{ commit.message | upper_first }}\
17
+ {% if commit.remote.pr_number %} in #{{ commit.remote.pr_number }}{% endif %}\
18
+ {% if commit.remote.username %} by @{{ commit.remote.username }}{% endif %}\
19
+ {% if not commit.remote.pr_number %} ({{ commit.id | truncate(length=7, end="") }}){% endif %}\
20
+ {% endfor %}
21
+ {% endfor %}
22
+ {% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
23
+ ### 🎉 新贡献者致谢 (New Contributors)
24
+ {% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
25
+ - 感谢 @{{ contributor.username }} 提交的首次贡献!
26
+ {% endfor %}
27
+ {% endif %}\n
28
+ """
29
+ trim = true
30
+
31
+ [git]
32
+ # 开启 Conventional Commits 解析
33
+ conventional_commits = true
34
+ # 即使未按规范前缀书写的普通提交也完整保留,杜绝漏掉任何变更
35
+ filter_unconventional = false
36
+ split_commits = false
37
+
38
+ commit_parsers = [
39
+ { message = "^.*!:|BREAKING CHANGE", group = "💥 破坏性更新 (Breaking Changes)" },
40
+ { message = "^feat", group = "🚀 新特性 (Features)" },
41
+ { message = "^fix", group = "🐛 缺陷修复 (Bug Fixes)" },
42
+ { message = "^perf", group = "⚡ 性能优化 (Performance)" },
43
+ { message = "^refactor", group = "🚜 代码重构 (Refactor)" },
44
+ { message = "^docs", group = "📝 文档变动 (Documentation)" },
45
+ { message = "^style", group = "🎨 代码格式 (Style)" },
46
+ { message = "^test", group = "🧪 测试相关 (Tests)" },
47
+ { message = "^build", group = "📦 构建与依赖 (Build)" },
48
+ { message = "^ci", group = "👷 持续集成 (CI)" },
49
+ { message = "^chore", group = "🧹 杂项维护 (Chore)" },
50
+ { message = "^revert", group = "⏪ 代码回滚 (Revert)" },
51
+ { body = ".*", group = "💼 其他变更 (Other)" },
52
+ ]
53
+
54
+ # 过滤与标签匹配规则
55
+ protect_breaking_commits = false
56
+ filter_commits = false
57
+ tag_pattern = "v?[0-9].*"
@@ -0,0 +1,78 @@
1
+ # ==============================================================================
2
+ # Docker 构建上下文忽略清单
3
+ # 避免将本地缓存、构建中间产物、样本文件及机密信息发送到 Docker 守护进程
4
+ # ==============================================================================
5
+
6
+ # 版本控制、CI、文档与本地测试
7
+ .git
8
+ .github
9
+ .githooks
10
+ scripts
11
+ docs
12
+ tests
13
+ .cliff.toml
14
+ .gitignore
15
+ .dockerignore
16
+ .editorconfig
17
+ .gitattributes
18
+
19
+ # 操作系统、IDE 与临时目录
20
+ .DS_Store
21
+ Thumbs.db
22
+ .idea
23
+ .vscode
24
+ tmp
25
+ temp
26
+ .tmp
27
+ .temp
28
+ *.tmp
29
+ *.temp
30
+ scratch
31
+ .scratch
32
+ scratchpad
33
+ .scratchpad
34
+ sandbox
35
+ .sandbox
36
+
37
+ # 测试覆盖率与代码分析缓存
38
+ coverage
39
+ *.lcov
40
+ .coverage
41
+ .coverage.*
42
+ htmlcov
43
+ .pytest_cache
44
+ .ruff_cache
45
+ .mypy_cache
46
+
47
+ # 敏感文件与本地环境变量
48
+ .env
49
+ .env.*
50
+ !.env.example
51
+
52
+ # 日志与本地逆向样本
53
+ *.log
54
+ logs
55
+ samples
56
+ *.exe
57
+ *.dll
58
+ *.sys
59
+ *.so
60
+ *.dylib
61
+ *.bin
62
+ *.dmp
63
+ *.idb
64
+ *.i64
65
+
66
+ # Python & uv 本地环境与构建产物
67
+ __pycache__
68
+ *.pyc
69
+ *.pyo
70
+ *.pyd
71
+ .Python
72
+ build/
73
+ dist/
74
+ wheels/
75
+ *.egg-info/
76
+ env/
77
+ venv/
78
+ .venv/
@@ -0,0 +1,24 @@
1
+ # EditorConfig 跨编辑器代码格式规范
2
+ # 详见: https://editorconfig.org
3
+
4
+ root = true
5
+
6
+ [*]
7
+ charset = utf-8
8
+ end_of_line = lf
9
+ indent_style = space
10
+ indent_size = 2
11
+ insert_final_newline = true
12
+ trim_trailing_whitespace = true
13
+
14
+ [*.py]
15
+ indent_size = 4
16
+
17
+ [*.{json,yml,yaml,toml,sh}]
18
+ indent_size = 2
19
+
20
+ [*.md]
21
+ trim_trailing_whitespace = false
22
+
23
+ [Makefile]
24
+ indent_style = tab
@@ -0,0 +1,44 @@
1
+ # ==============================================================================
2
+ # Git 跨平台换行符自动归一化配置
3
+ # 强制所有文本文件统一使用 LF 换行符,杜绝 Windows CRLF 导致 Linux 脚本崩溃
4
+ # ==============================================================================
5
+
6
+ # 默认自动检测文本并统一换行为 LF
7
+ * text=auto eol=lf
8
+
9
+ # 纯文本与配置文件强制 LF
10
+ .githooks/* text eol=lf
11
+ *.sh text eol=lf
12
+ *.bash text eol=lf
13
+ *.zsh text eol=lf
14
+ *.py text eol=lf
15
+ *.toml text eol=lf
16
+ Dockerfile text eol=lf
17
+ *.yml text eol=lf
18
+ *.yaml text eol=lf
19
+ *.json text eol=lf
20
+ *.md text eol=lf
21
+
22
+ # Windows 专用脚本保留 CRLF
23
+ *.bat text eol=crlf
24
+ *.cmd text eol=crlf
25
+ *.ps1 text eol=crlf
26
+
27
+ # 二进制与逆向分析制品声明
28
+ *.png binary
29
+ *.jpg binary
30
+ *.jpeg binary
31
+ *.gif binary
32
+ *.ico binary
33
+ *.zip binary
34
+ *.tar.gz binary
35
+ *.whl binary
36
+ *.exe binary
37
+ *.dll binary
38
+ *.sys binary
39
+ *.so binary
40
+ *.dylib binary
41
+ *.elf binary
42
+ *.macho binary
43
+ *.bin binary
44
+ *.dmp binary
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env bash
2
+ # ==============================================================================
3
+ # Conventional Commits 本地提交通用规范校验钩子
4
+ #
5
+ # 在本地提交阶段自动校验提交说明首行格式,智能放行 Merge、Revert 与临时变基提交,
6
+ # 格式不合规时进行拦截并输出友好诊断指引与交互向导建议。
7
+ #
8
+ # @author Ateng
9
+ # @since 2026-10-13
10
+ # ==============================================================================
11
+
12
+ set -eo pipefail
13
+
14
+ MSG_FILE="$1"
15
+
16
+ if [ ! -f "$MSG_FILE" ]; then
17
+ exit 0
18
+ fi
19
+
20
+ # 提取第一行非注释内容并去除首尾空白
21
+ FIRST_LINE=$(grep -v '^#' "$MSG_FILE" | head -n 1 | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
22
+
23
+ # 若内容为空,交由 Git 原生逻辑拦截
24
+ if [ -z "$FIRST_LINE" ]; then
25
+ exit 0
26
+ fi
27
+
28
+ # 1. 自动放行机制 (Merge, Revert, 临时变基)
29
+ if echo "$FIRST_LINE" | grep -Eq '^(Merge (branch|tag|remote-tracking branch|pull request)|Revert |(fixup|squash)!)'; then
30
+ exit 0
31
+ fi
32
+
33
+ # 2. Conventional Commits 正则校验
34
+ # 格式: <type>(<scope>)<!>: <subject>
35
+ CONVENTIONAL_REGEX="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9._-]+\))?!?: .+$"
36
+
37
+ if ! echo "$FIRST_LINE" | grep -Eq "$CONVENTIONAL_REGEX"; then
38
+ # 终端色彩适配
39
+ if [ -t 1 ]; then
40
+ COLOR_RESET="\033[0m"
41
+ COLOR_BOLD="\033[1m"
42
+ COLOR_RED="\033[31m"
43
+ COLOR_YELLOW="\033[33m"
44
+ COLOR_CYAN="\033[36m"
45
+ else
46
+ COLOR_RESET=""
47
+ COLOR_BOLD=""
48
+ COLOR_RED=""
49
+ COLOR_YELLOW=""
50
+ COLOR_CYAN=""
51
+ fi
52
+
53
+ printf "\n%b[ERROR] 提交信息不符合 Conventional Commits 规范!%b\n" "${COLOR_RED}" "${COLOR_RESET}"
54
+ printf "当前提交信息: %b\"%s\"%b\n\n" "${COLOR_BOLD}" "$FIRST_LINE" "${COLOR_RESET}"
55
+ printf "%b规范格式:%b <type>(<scope>): <subject>\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
56
+ printf "%b支持类型:%b feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
57
+ printf "%b参考示例:%b\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
58
+ printf " feat: 支持 PE64 导入表解析\n"
59
+ printf " fix(parser): 修复空节区熵计算异常\n"
60
+ printf " docs: 完善项目接入文档\n\n"
61
+ printf "💡 %b建议直接运行交互式向导快速提交:%b %bbash scripts/commit.sh%b\n\n" "${COLOR_CYAN}" "${COLOR_RESET}" "${COLOR_BOLD}" "${COLOR_RESET}"
62
+ exit 1
63
+ fi
64
+
65
+ exit 0
@@ -0,0 +1,12 @@
1
+ # ==============================================================================
2
+ # GitHub 代码属主与审阅者自动指派配置 (Code Owners)
3
+ # 详见: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
4
+ # ==============================================================================
5
+
6
+ # 全局默认所有者(通配所有未被下级路径覆盖的文件)
7
+ * @atengk
8
+
9
+ # 核心基础设施与自动化流水线重点守护
10
+ /.github/ @atengk
11
+ /scripts/ @atengk
12
+ /.githooks/ @atengk
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: "Bug 报告"
3
+ about: 报告项目中出现的错误或异常行为
4
+ title: "fix: [简要描述该问题]"
5
+ labels: ["bug"]
6
+ assignees: ""
7
+ ---
8
+
9
+ ### 缺陷描述
10
+ <!-- 清晰且简要地描述该问题是什么 -->
11
+
12
+ ### 重现步骤
13
+ 1. 调用工具或执行命令 '...'
14
+ 2. 传入参数或目标二进制格式(PE / ELF / Mach-O)'...'
15
+ 3. 观察到报错 '...'
16
+
17
+ ### 期望结果
18
+ <!-- 描述你期望发生的正常行为 -->
19
+
20
+ ### 实际结果与日志
21
+ <!-- 贴出完整的报错堆栈、--doctor 自检输出或 MCP 响应内容 -->
22
+ ```text
23
+
24
+ ```
25
+
26
+ ### 环境信息
27
+ - **操作系统**: [例如 Windows 11, macOS 14, Ubuntu 24.04]
28
+ - **Python & uv 版本**: [例如 Python 3.12, uv 0.12.x]
29
+ - **外部工具状态 (`mcp-server-reverse --doctor`)**: [例如 radare2 / objdump / floss 是否启用]
30
+ - **项目版本**: [例如 v0.1.0 或 git commit hash]
@@ -0,0 +1,16 @@
1
+ # ==============================================================================
2
+ # GitHub Issues 治理配置
3
+ # 详见: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
4
+ # ==============================================================================
5
+
6
+ # 关闭无模板空白 Issue 入口,防止无效提交
7
+ blank_issues_enabled: false
8
+
9
+ # 导流外链:引导用户提问或查阅文档
10
+ contact_links:
11
+ - name: 💬 社区技术答疑与使用交流 (GitHub Discussions)
12
+ url: https://github.com/atengk/mcp-server-reverse/discussions
13
+ about: 请在此讨论配置用法、提问咨询或分享实践,避免占用 Issue 跟踪。
14
+ - name: 📖 项目官方主页与文档 (Documentation)
15
+ url: https://github.com/atengk/mcp-server-reverse#readme
16
+ about: 查阅快速开始指南、MCP Tools 列表及自动化发版机制说明。
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: "需求与特性建议"
3
+ about: 为项目提出新功能建议或设计优化方案
4
+ title: "feat: [简要描述新特性]"
5
+ labels: ["enhancement"]
6
+ assignees: ""
7
+ ---
8
+
9
+ ### 需求背景与痛点
10
+ <!-- 描述当前逆向分析场景遇到的阻碍或不便:为什么需要这个新特性? -->
11
+
12
+ ### 建议的解决方案
13
+ <!-- 清晰且详细地描述你建议的实现方式、MCP Tool 契约或功能形态 -->
14
+
15
+ ### 替代方案或权衡考虑
16
+ <!-- 是否尝试过或考虑过其他替代做法? -->
17
+
18
+ ### 补充上下文
19
+ <!-- 如有相关截图、参考资料或链接,请在此提供 -->
@@ -0,0 +1,25 @@
1
+ ## 变更说明
2
+ <!-- 请简要说明此 PR 解决的问题或新增的能力 -->
3
+
4
+ ## 关联 Issue
5
+ - 修复/关联: close #
6
+
7
+ ## 变更类型
8
+ <!-- 请在符合项的括号内填入 x,例如 [x](与 CI Conventional Commits 门禁规范严格保持一致) -->
9
+ - [ ] `feat`: 新增功能
10
+ - [ ] `fix`: 缺陷修复
11
+ - [ ] `docs`: 文档变动
12
+ - [ ] `style`: 代码格式调整(不影响业务逻辑)
13
+ - [ ] `refactor`: 代码重构(非新功能、非修复)
14
+ - [ ] `perf`: 性能优化
15
+ - [ ] `test`: 补全或重构测试
16
+ - [ ] `build`: 构建系统或外部依赖变动
17
+ - [ ] `ci`: CI/CD 自动化流水线变动
18
+ - [ ] `chore`: 其他常规维护与辅助工具变动
19
+ - [ ] `revert`: 撤销/恢复先前的提交
20
+
21
+ ## 自检清单
22
+ - [ ] 提交信息符合 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/) 规范
23
+ - [ ] 本地已通过全部已有测试及代码检查 (`uv run ruff check .` & `uv run pytest`)
24
+ - [ ] 如有新增/修改功能,已补充对应测试用例
25
+ - [ ] 如涉及 API 或配置变更,已同步更新相关文档
@@ -0,0 +1,63 @@
1
+ # ==============================================================================
2
+ # Dependabot 依赖自动化更新配置 (Dependabot Version Updates)
3
+ #
4
+ # 机制说明:
5
+ # 1. 本配置负责常规月度依赖升级(Version Updates),采用语义化双轨模型聚合 PR;
6
+ # 2. 涵盖 GitHub Actions、Python (pip/uv) 与 Docker 基础镜像三大生态。
7
+ # ==============================================================================
8
+
9
+ version: 2
10
+ updates:
11
+ # 1. 持续监控 GitHub Actions 工作流版本更新
12
+ - package-ecosystem: "github-actions"
13
+ directory: "/"
14
+ schedule:
15
+ interval: "monthly"
16
+ open-pull-requests-limit: 5
17
+ commit-message:
18
+ prefix: "ci"
19
+ include: "scope"
20
+ labels:
21
+ - "dependencies"
22
+ groups:
23
+ actions:
24
+ patterns:
25
+ - "*"
26
+ update-types:
27
+ - "minor"
28
+ - "patch"
29
+
30
+ # 2. 持续监控 Python 依赖更新 (pyproject.toml / uv.lock)
31
+ - package-ecosystem: "pip"
32
+ directory: "/"
33
+ schedule:
34
+ interval: "monthly"
35
+ open-pull-requests-limit: 5
36
+ commit-message:
37
+ prefix: "build"
38
+ include: "scope"
39
+ labels:
40
+ - "dependencies"
41
+ groups:
42
+ dependencies:
43
+ patterns:
44
+ - "*"
45
+ update-types:
46
+ - "minor"
47
+ - "patch"
48
+
49
+ # 3. 持续监控 Dockerfile 容器基础镜像更新
50
+ - package-ecosystem: "docker"
51
+ directory: "/"
52
+ schedule:
53
+ interval: "monthly"
54
+ open-pull-requests-limit: 5
55
+ commit-message:
56
+ prefix: "build"
57
+ include: "scope"
58
+ labels:
59
+ - "dependencies"
60
+ groups:
61
+ docker-images:
62
+ patterns:
63
+ - "*"
@@ -0,0 +1,111 @@
1
+ # ==============================================================================
2
+ # 工作流:Python 持续集成与质量守门流水线 (Python CI)
3
+ # 适用场景:mcp-server-reverse 的 PR 门禁、Shell 脚本检查、Ruff 静态分析与单元测试
4
+ # 触发条件:
5
+ # - push: 主干分支 (main, master) 代码推送
6
+ # - pull_request: 针对主干分支的 PR 创建、编辑、代码同步
7
+ # 核心特性:
8
+ # - Conventional Commits PR 标题规范静态校验
9
+ # - 工程内置自动化脚本 (scripts/*.sh) 与 Git 钩子 (.githooks/*) ShellCheck 静态分析
10
+ # - 基于 astral-sh/setup-uv 的极速 Python 3.12 环境与依赖缓存
11
+ # - Ruff 代码风格校验 (check) 与格式化校验 (format --check)
12
+ # - pytest 自动化单元测试与覆盖率统计
13
+ # ==============================================================================
14
+
15
+ name: CI
16
+
17
+ on:
18
+ push:
19
+ branches: [main, master]
20
+ pull_request:
21
+ branches: [main, master]
22
+ types: [opened, edited, synchronize, reopened]
23
+
24
+ # 并发控制:同一分支/PR 有新提交时自动取消正在执行的陈旧构建,防止竞态并节省 Runner 资源
25
+ concurrency:
26
+ group: ${{ github.workflow }}-${{ github.ref }}
27
+ cancel-in-progress: true
28
+
29
+ # 最小权限原则:仅授予代码仓库读取权限
30
+ permissions:
31
+ contents: read
32
+
33
+ jobs:
34
+ # ----------------------------------------------------------------------------
35
+ # Job 1: PR 标题规范校验 (仅在 PR 触发时执行)
36
+ # ----------------------------------------------------------------------------
37
+ validate-pr-title:
38
+ name: 校验 PR 标题规范
39
+ runs-on: ubuntu-latest
40
+ if: github.event_name == 'pull_request'
41
+ permissions:
42
+ pull-requests: read
43
+ steps:
44
+ - name: 校验 PR 标题符合 Conventional Commits
45
+ uses: amannn/action-semantic-pull-request@v6
46
+ env:
47
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
48
+ with:
49
+ types: |
50
+ feat
51
+ fix
52
+ docs
53
+ style
54
+ refactor
55
+ perf
56
+ test
57
+ build
58
+ ci
59
+ chore
60
+ revert
61
+
62
+ # ----------------------------------------------------------------------------
63
+ # Job 2: 脚本语法校验、Python 静态检查与单元测试
64
+ # ----------------------------------------------------------------------------
65
+ test:
66
+ name: 静态检查、格式化与测试 (Python + uv)
67
+ runs-on: ubuntu-latest
68
+
69
+ steps:
70
+ - name: 检出源码
71
+ uses: actions/checkout@v4
72
+
73
+ - name: 静态校验工程脚本与 Git 钩子语法与规范 (Bash Syntax & ShellCheck)
74
+ run: |
75
+ if ls scripts/*.sh >/dev/null 2>&1; then
76
+ bash -n scripts/*.sh
77
+ shellcheck --severity=warning scripts/*.sh
78
+ fi
79
+ if [ -d .githooks ]; then
80
+ HOOK_FILES=$(grep -l '^#!' .githooks/* 2>/dev/null || true)
81
+ if [ -n "$HOOK_FILES" ]; then
82
+ echo "$HOOK_FILES" | xargs -r bash -n
83
+ echo "$HOOK_FILES" | xargs -r shellcheck --severity=warning
84
+ fi
85
+ fi
86
+
87
+ - name: 安装 uv 并配置 Python 环境
88
+ uses: astral-sh/setup-uv@v5
89
+ with:
90
+ enable-cache: true
91
+ python-version: '3.12'
92
+
93
+ - name: 安装项目与开发依赖
94
+ run: uv sync --all-extras --dev
95
+
96
+ - name: 代码风格与语法检查 (Ruff Linter & Formatter)
97
+ run: |
98
+ if [ -d src ] || [ -d tests ]; then
99
+ uv run ruff check .
100
+ uv run ruff format --check .
101
+ else
102
+ echo "暂未发现 Python 源码目录,跳过 Ruff 检查。"
103
+ fi
104
+
105
+ - name: 运行单元测试与覆盖率统计
106
+ run: |
107
+ if find tests -name "test_*.py" -o -name "*_test.py" 2>/dev/null | grep -q .; then
108
+ uv run pytest --cov=mcp_server_reverse
109
+ else
110
+ echo "暂未发现测试用例文件,跳过 pytest 执行。"
111
+ fi
@@ -0,0 +1,101 @@
1
+ # ==============================================================================
2
+ # 工作流:Python 多架构容器镜像构建与发布 (Python Docker - GHCR)
3
+ # 适用场景:mcp-server-reverse 在隔离容器/远程环境中以 SSE / Streamable-HTTP 模式部署 (linux/amd64, linux/arm64)
4
+ # 触发通道:
5
+ # - 主干分支推送 (push branches: main, master):自动构建并推送带有 latest 与 short-sha 标签的镜像
6
+ # - 语义化标签推送 (push tags: v*):自动解析并生成 SemVer 镜像标签 (如 v1.0.0, 1.0)
7
+ # - 网页手动触发 (workflow_dispatch)
8
+ # ==============================================================================
9
+
10
+ name: Docker (GHCR)
11
+
12
+ on:
13
+ push:
14
+ branches: [main, master]
15
+ tags:
16
+ - 'v*'
17
+ workflow_dispatch:
18
+
19
+ # 并发控制:同一分支有新构建时自动取消旧任务;标签构建独立执行
20
+ concurrency:
21
+ group: ${{ github.workflow }}-${{ github.ref }}
22
+ cancel-in-progress: true
23
+
24
+ permissions:
25
+ contents: read
26
+
27
+ jobs:
28
+ build-and-push:
29
+ name: 构建并推送多架构容器镜像
30
+ runs-on: ubuntu-latest
31
+ permissions:
32
+ contents: read
33
+ packages: write # 推送至 GHCR (ghcr.io) 所需的镜像包写入权限
34
+ steps:
35
+ - name: 转换仓库名称为全小写 (Lowercase Repository Name)
36
+ run: echo "REPO_LC=${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
37
+
38
+ - name: 检出源码
39
+ uses: actions/checkout@v4
40
+ with:
41
+ fetch-depth: 0
42
+
43
+ - name: 检查分支提交是否关联发版标签 (防双跑自检)
44
+ id: check-tag
45
+ if: github.event_name == 'push' && github.ref_type == 'branch'
46
+ run: |
47
+ git fetch --tags --force
48
+ MATCHED_TAGS=$(git tag --points-at HEAD 'v*' 2>/dev/null || true)
49
+ if [ -n "$MATCHED_TAGS" ]; then
50
+ TAGS_STR=$(echo "$MATCHED_TAGS" | tr '\n' ' ' | sed 's/[[:space:]]*$//')
51
+ echo "检测到当前分支提交已关联语义化版本标签: [$TAGS_STR]"
52
+ echo "当前构建将由 Tag 流水线统一发布,自动跳过分支构建以避免重复计算与镜像竞态。"
53
+ echo "skip=true" >> "$GITHUB_OUTPUT"
54
+ else
55
+ echo "当前分支提交未关联发版标签,继续执行容器镜像构建。"
56
+ echo "skip=false" >> "$GITHUB_OUTPUT"
57
+ fi
58
+
59
+ - name: 设置 QEMU 模拟器 (多架构支持)
60
+ if: steps.check-tag.outputs.skip != 'true'
61
+ uses: docker/setup-qemu-action@v4
62
+
63
+ - name: 设置 Docker Buildx
64
+ if: steps.check-tag.outputs.skip != 'true'
65
+ uses: docker/setup-buildx-action@v4
66
+
67
+ - name: 登录 GHCR
68
+ if: steps.check-tag.outputs.skip != 'true'
69
+ uses: docker/login-action@v4
70
+ with:
71
+ registry: ghcr.io
72
+ username: ${{ github.actor }}
73
+ password: ${{ secrets.GITHUB_TOKEN }}
74
+
75
+ - name: 提取 Docker 镜像元数据 (自动计算 SemVer 标签)
76
+ id: meta
77
+ if: steps.check-tag.outputs.skip != 'true'
78
+ uses: docker/metadata-action@v6
79
+ with:
80
+ images: |
81
+ ghcr.io/${{ env.REPO_LC }}
82
+ flavor: |
83
+ latest=${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' || (startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-')) }}
84
+ tags: |
85
+ type=sha,format=short
86
+ type=semver,pattern={{version}}
87
+ type=semver,pattern={{major}}.{{minor}}
88
+
89
+ - name: 构建并推送多架构镜像 (amd64 / arm64)
90
+ if: steps.check-tag.outputs.skip != 'true'
91
+ uses: docker/build-push-action@v7
92
+ with:
93
+ context: .
94
+ push: true
95
+ platforms: linux/amd64,linux/arm64
96
+ tags: ${{ steps.meta.outputs.tags }}
97
+ labels: ${{ steps.meta.outputs.labels }}
98
+ provenance: false
99
+ sbom: false
100
+ cache-from: type=gha
101
+ cache-to: type=gha,mode=max