ppsspp-dfx-mcp 0.1.2__tar.gz

ppsspp_dfx_mcp-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: pytest (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        # 单版本策略：SDK v2 导入路径依赖 3.14 新特性（见 pyproject
+        # requires-python）。放宽到矩阵多版本前先解除该耦合。
+        python-version: ["3.14"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (editable, with dev extras)
+        run: pip install -e .[dev]
+
+      - name: Sanity — entry point importable
+        run: python -c "import ppsspp_dfx_mcp; print('import ok')"
+
+      # 集成测试中需要真实 PPSSPP / ISO 的用例按设计自动 skip；
+      # 其余（单元 + 契约 + fixture 化集成）必须三平台全绿。
+      - name: Run test suite
+        run: python -m pytest tests -q
+
+  ci-ok:
+    name: ci-ok
+    needs: test
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    steps:
+      - name: Verify all matrix legs passed
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ]; then
+            echo "matrix did not fully succeed: ${{ needs.test.result }}"
+            exit 1
+          fi
+          echo "all matrix legs passed"

ppsspp_dfx_mcp-0.1.2/.github/workflows/pypi-publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+# 两段式发布：
+#   阶段一  push tag v*         → 构建 + 试发布到 TestPyPI，验证无误后再进阶段二
+#   阶段二  GitHub Release 发布 → 同一 tag 重新构建 + 正式发布到 pypi.org
+# 两阶段共用本文件：两平台 Trusted Publisher 注册均为
+# workflow 文件名 = pypi-publish.yml / environment = pypi（OIDC，不用 API token）。
+# 人工门禁 = 阶段二的 Release 发布按钮；因此不要在 GitHub 的 pypi 环境
+# 上加 Required reviewers，否则阶段一也会被卡。
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-testpypi:
+    name: build & publish → test.pypi.org
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Guard — tag 与 pyproject 版本一致
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          FILE=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$FILE" ]; then
+            echo "::error::tag v$TAG 与 pyproject.toml 版本 $FILE 不一致"
+            exit 1
+          fi
+
+      - name: Build sdist & wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # 缺省时该 action 上传到正式 PyPI；TestPyPI 必须显式指定。
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: build & publish → pypi.org
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Guard — tag 与 pyproject 版本一致
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          FILE=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$FILE" ]; then
+            echo "::error::tag v$TAG 与 pyproject.toml 版本 $FILE 不一致"
+            exit 1
+          fi
+
+      - name: Build sdist & wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ppsspp_dfx_mcp-0.1.2/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+
+# Local secrets (evals LLM endpoint config — never commit)
+evals/llm_api.json
+
+# Runtime output of the debug toolchain
+.ppsspp-dfx/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store

ppsspp_dfx_mcp-0.1.2/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "ppsspp-dfx": {
+      "command": ".venv/ppsspp-dfx-mcp/Scripts/python.exe",
+      "args": [
+        "-m",
+        "ppsspp_dfx_mcp"
+      ],
+      "cwd": "${CLAUDE_PROJECT_DIR}",
+      "env": {
+        "PPSSPP_DFX_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}

ppsspp_dfx_mcp-0.1.2/CHANGELOG.md

@@ -0,0 +1,54 @@
+# 更新日志
+
+本项目的所有显著变更将记录在此文件。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.1.2] - 2026-09-17
+
+### Fixed
+
+- MCP 握手的 serverInfo 版本改为从包元数据读取（`importlib.metadata`），
+  消除 `__init__.py` 中与 pyproject 脱节的硬编码副本——0.1.1 曾在协议层
+  自报 0.1.0。
+- README：Windows 的 venv 创建命令更正为 `py -3.14`
+  （`python3.14` 别名在 Windows 上通常不存在）。
+
+## [0.1.1] - 2026-09-17
+
+### Added
+
+- **配置模板三件套**（`examples/`）：`project.yaml` / `addresses.yaml` /
+  `scripts.manifest.yaml` 可拷贝模板，PLACEHOLDER 标注 + 逐字段语义注释，
+  独立部署时 `mkdir -p .ppsspp-dfx/config && cp examples/*.yaml
+  .ppsspp-dfx/config/` 即可起步。
+- **预置 `.mcp.json`**：独立 checkout 的开箱即用 MCP 客户端注册。
+- `check_env.py --check` 对 `scripts.manifest.yaml` 缺失显式告警（非阻断）
+  并给出 examples 修复路径——此前缺失会导致 `ppsspp_script_*` 工具静默消失。
+- **README 新增「故障排查速查表」与「已知限制」**：错误码体系的症状级
+  索引 + 协议面边界的诚实汇总。
+- **`docs/SCOPE.md`**：PPSSPP WS 事件 → 工具映射的人读版 + 刻意未工具化
+  事件清单（机器可读真相源仍为 `ws_contract.py`）。
+- 随包 `.github/workflows/`：三平台测试矩阵（CI）与两段式发布工作流——
+  push tag `v*` 构建并试发布（内部验证），确认后发布 GitHub Release 正式
+  上架 PyPI；两阶段均为 trusted publishing（OIDC），内置 tag/版本一致性 Guard。
+
+### Changed
+
+- README 定位为中文社区发布；代码注释与工具 docstring 保持英文
+  （协议面被工具面基线锁定）。
+- README 参考 deepseek-harness 的官方 README 结构重构为发布版形态：
+  PyPI 安装为主路径（含安装后的 `.mcp.json` 与命令示例），新增项目状态、
+  致谢与引用节。
+
+## [0.1.0] - 2026-09-16
+
+### Added
+
+- 首个开源发布版本：41 个静态 MCP 工具（全结构化 inputSchema/outputSchema）、
+  动态诊断脚本工具（manifest 驱动）、多会话管理与楔死自愈、后台批处理、
+  原生 replay 录制回放、GPU 缓冲/纹素/CLUT 转储、HLE 内省、盲测评估体系
+  （21 场景卡 + 确定性门禁）。

ppsspp_dfx_mcp-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Contributing to ppsspp-dfx-mcp
+
+Thanks for your interest in improving the project. This document defines the
+documentation and comment conventions every source file must follow, plus the
+practical notes for getting a development environment running.
+
+## Development setup
+
+The server requires an isolated venv: it imports MCP SDK v2
+(`mcp.server.mcpserver`), which cannot coexist with the 1.x `mcp` package that
+many other MCP servers pin.
+
+```bash
+# From the repository root — creates .venv/ppsspp-dfx-mcp and installs
+# (editable, with dev extras):
+python scripts/check_env.py --bootstrap
+
+# Verify interpreter / SDK version / package import:
+python scripts/check_env.py --check
+
+# Run the test suite:
+.venv/ppsspp-dfx-mcp/Scripts/python -m pytest tests -q    # Windows
+.venv/ppsspp-dfx-mcp/bin/python -m pytest tests -q        # POSIX
+```
+
+## Module docstrings (file headers)
+
+Every module opens with a short docstring that answers **what this is, why it
+exists (only if non-obvious), and the key contract or invariant** a reader
+must know before changing it. Rules:
+
+1. **Length**: aim for ≤ 10 lines. A header that needs more than that usually
+   means the module is doing too much.
+2. **No history.** Never reference when or why a change happened, no dates,
+   no change IDs (`W1 fix`, `D-19`, `R15`, `建议3`, `review issue #N`,
+   `spike U2`, `acceptance 7`, `Phase 2`, `A1/A2`…). That information lives in
+   version control.
+3. **No dead links.** Reference only documentation that ships with the
+   project (this file, `tests/`, tool docstrings). Do not link to workspace
+   planning/analysis documents — if the underlying fact matters, state the
+   fact itself in one line instead.
+4. **Tool modules** list the tools they expose with one line each.
+
+Example:
+
+```python
+"""Memory tool wrappers.
+
+3 tools exposed:
+- ppsspp_read_memory(action, ...) — aggregate read (bytes/u32/string/scan)
+- ppsspp_write_memory(address, data, format?) — write u32 or bytes
+- ppsspp_disassemble(address, count?) — disassemble N instructions
+
+Reads and writes go through the session's debug client; protected ranges
+(kernel, top.prx code) reject writes unless force=True.
+"""
+```
+
+## Inline comments
+
+A comment earns its place only when it states a constraint the code cannot
+show: a non-obvious invariant, a race condition, a protocol quirk, an order of
+operations that must not change.
+
+1. **No changelog comments.** Same rule as headers — no fix IDs, no dates, no
+   issue numbers, no "this used to be X". If the old behaviour matters, the
+   constraint it produced is what you write down.
+2. **Explain why, not what.** `# increment retry counter` is noise;
+   `# the probe must run before the handshake or PPSSPP answers with an
+   empty frame` is a comment.
+3. Placement: own line above the code it governs.
+
+## Tool docstrings are protocol surface
+
+The docstring of each tool function in `src/ppsspp_dfx_mcp/tools/` is the
+description the MCP client shows to models. It follows the
+PURPOSE / USAGE / BEHAVIOR / RETURNS convention and is locked by a contract
+test against a committed baseline. **Do not reword tool docstrings** in
+refactors: changing them changes the tool surface every client sees. Treat
+them like a public API.
+
+## Tests
+
+- New behaviour needs a test next to the layer it belongs to
+  (`tests/unit/…` mirroring `src/`, contract tests in
+  `tests/unit/l2_mcp_contract/`).
+- Test names describe the behaviour they lock in; the module docstring may
+  summarise what a test file locks in, under the same no-history rules.
+
+## Pull requests
+
+- Keep the change surgical: every line should trace back to the purpose of
+  the PR.
+- Run the full test suite before pushing.
+- If a change touches tool signatures, descriptions, or output contracts,
+  regenerate the tool-surface baseline
+  (`scripts/dump_tool_surface.py`) **in the same commit** and say so in the
+  description.
+
+## File naming
+
+- `scripts/` executables: verb-first snake_case — `<verb>_<object>.py`
+  (`dump_tool_surface.py`, `check_env.py`, `record_fixtures.py`).
+  Private helpers take a leading underscore (`_wire.py`); data files keep a
+  descriptive name with their real extension.
+- `evals/` modules: snake_case, one purpose per module; tests follow
+  `test_<subject>.py`.
+- Evaluation reports are development-process artifacts and are NOT
+  committed to this repository: `report-<topic>-<YYYYMMDD>.md`.
+
+## Test layers
+
+`tests/unit` is organized in four layers — place a new test by what it
+locks, not by where similar-looking code lives:
+
+| Layer | Locks | A test belongs here when… |
+|---|---|---|
+| `unit/core` | Domain primitives | The pure function/class under `core/` (parsers, address math, path resolution) |
+| `unit/l1_contract` | PPSSPP wire contract | The shape/semantics of a WS event as the transport sees it |
+| `unit/l2_mcp_contract` | MCP tool surface | Tool signatures, descriptions, schemas, error codes, annotations |
+| `unit/l3_orchestration` | Session/transport orchestration | Multi-component behaviour across session manager, client helper, observers |
+| `unit/l4_regression` | One historical defect per file | A specific shipped bug must never reappear |
+
+`tests/integration/` requires a real PPSSPP + ISO (auto-skips when absent);
+its modules are marked `integration` + `real_ppsspp`.
+
+## Testing conventions
+
+- **Does-not-raise tests**: calling the function bare is accepted, but if it
+  returns a value, assert it (`assert fn(...) is None`). A bare call cannot
+  distinguish "returned None" from "returned garbage".
+- **Patching `is_pid_alive`**: production reads it as
+  `proc.is_pid_alive(...)` (module attribute) — patch
+  `ppsspp_dfx_mcp.core.proc.is_pid_alive`, never a stale re-export.
+- **Tool-surface baseline**: `tests/unit/l2_mcp_contract/tool_surface_baseline.json`
+  snapshots the *static* registry (41 tools). Manifest scripts add dynamic
+  `ppsspp_script_*` tools at runtime, so a live server's `tool_count` is
+  baseline + manifest count.

ppsspp_dfx_mcp-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ppsspp-dfx-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.