flac-mcp 0.1.0__tar.gz

flac_mcp-0.1.0/.dockerignore

@@ -0,0 +1,30 @@
+# Keep the build context small. Only the bridge source actually needs to be
+# copied into the image (see Dockerfile), but rather than allowlisting we
+# block the heavy/irrelevant trees.
+
+.git/
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Bridge probe scripts and their captured outputs -- dev artifacts that
+# don't belong in the runtime image.
+pfc-mcp-bridge/scratch/
+
+# MCP-side package and tests don't need to be inside the container yet -- the
+# container only runs the bridge. Comment out if you later want them available.
+src/
+tests/
+docs/
+.pfc-mcp/
+.pfc-mcp-bridge/
+
+# IDE / OS junk
+.idea/
+.vscode/
+.DS_Store

flac_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish flac-mcp
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv sync --group dev
+      - run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk -v ver="$VERSION" '
+            BEGIN { marker = "## [" ver "]" }
+            index($0, marker) == 1 { found=1; next }
+            found && index($0, "## [") == 1 { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "::error::No CHANGELOG entry found for version $VERSION in CHANGELOG.md"
+            exit 1
+          fi
+          echo "--- release notes ---"
+          cat release-notes.md
+
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: softprops/action-gh-release@v3
+        with:
+          body_path: release-notes.md
+          files: dist/*

flac_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv sync --group dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy src/flac_mcp/
+      - run: uv run pytest tests/ --cov=flac_mcp --cov-report=term-missing

flac_mcp-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+
+# Environments
+.venv/
+*.env
+
+# Local agent/MCP config
+.mcp.json
+.claude/
+.codex/
+
+# Local runtime/temp artifacts
+.pfc-mcp-bridge/
+.tmp/
+.pytest_tmp/
+
+# Docker dev container's user workspace (mounted into container at /workspace).
+# Keep the dir itself via .gitkeep, ignore everything dropped inside.
+workspace/*
+!workspace/.gitkeep
+
+# macOS
+.DS_Store
+
+# Windows / MSYS-Cygwin crash dumps
+*.stackdump

flac_mcp-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "itasca-mcp-bridge"]
+	path = itasca-mcp-bridge
+	url = https://github.com/yusong652/itasca-mcp-bridge.git

flac_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md
+
+Guidance for coding agents working in the `flac-mcp` repository.
+
+## Project Overview
+
+`flac-mcp` provides an MCP server for ITASCA FLAC workflows plus a bridge runtime that runs inside FLAC GUI.
+
+This repository intentionally has two runtime contexts:
+
+- `src/flac_mcp/` (Python >= 3.10): MCP server package used by clients/tooling
+- `itasca-mcp-bridge/` (FLAC embedded Python, often 3.6): WebSocket bridge running inside FLAC GUI
+
+Treat these as separate deployment targets even though they live in one repository.
+
+## Core Architecture
+
+### MCP side (`src/flac_mcp`)
+
+- Exposes documentation tools and execution tools through FastMCP
+- Communicates with bridge via WebSocket client (`flac_mcp.bridge.client`)
+- Returns a unified tool envelope: `ok`, `data`, `error`
+- Dual execution model: synchronous REPL (`flac_execute_code`) for quick queries, script-first async (`flac_execute_task` + `flac_check_task_status`) for long-running simulations
+
+### Bridge side (`itasca-mcp-bridge`)
+
+- Runs in FLAC GUI process
+- Owns thread-safe interaction with ITASCA SDK
+- Handles long-running tasks and diagnostics
+- Must be started from FLAC GUI (for example with `%run .../itasca-mcp-bridge/start_bridge.py`)
+
+## Repository Layout
+
+```text
+flac-mcp/
+├── src/flac_mcp/
+│   ├── bridge/          # MCP-side bridge client/task manager
+│   ├── knowledge/       # command/API/reference search system
+│   ├── tools/           # MCP tool implementations
+│   ├── formatting.py    # shared response formatting
+│   └── server.py        # MCP server entrypoint
+├── itasca-mcp-bridge/      # runtime executed inside FLAC GUI
+└── tests/               # MCP/tool contract tests
+```
+
+## Development Commands
+
+Run from repository root.
+
+```bash
+uv sync
+uv sync --group dev
+uv run flac-mcp
+uv run pytest tests/test_phase2_tools.py
+uv run pytest tests/test_tool_contracts.py
+```
+
+## Engineering Rules
+
+1. Keep MCP and bridge concerns separate.
+   - Do not couple MCP logic to FLAC GUI internals.
+   - Do not introduce application/session policy into bridge runtime.
+
+2. Preserve execution semantics for each model.
+   - `flac_execute_code` runs synchronous snippets and returns stdout/result immediately.
+   - `flac_execute_task` submits scripts and returns quickly.
+   - Progress/result retrieval goes through `flac_check_task_status`.
+
+3. Maintain structured tool contracts.
+   - Prefer stable machine-readable keys over ad-hoc text parsing.
+   - Use the unified envelope for all tool business payloads:
+     - success: `{"ok": true, "data": ...}`
+     - error: `{"ok": false, "error": {"code": str, "message": str, "details"?: object}}`
+   - Enforce coherence: `ok=true` must not include `error`; `ok=false` must include `error`.
+   - Do not require duplicate presentation fields (for example, `display`) when they mirror structured data.
+   - Let clients render human-facing formatting from structured fields.
+   - Documentation tools must keep `data` consistent as:
+     - `source`: `"commands" | "python_api" | "reference"`
+     - `action`: `"browse" | "query"`
+     - `entries`: `list[object]`
+     - `summary`: `object` (counts/hints/context)
+   - Keep query/path/input echo minimal; prefer putting necessary context in `summary` or `error.details.input`.
+
+4. Keep compatibility when practical.
+   - If moving shared helpers, keep thin compatibility re-exports when tests or downstream code rely on old import paths.
+
+5. Respect runtime constraints.
+   - MCP package uses modern deps (`websockets>=15`).
+   - Bridge side may require legacy-compatible deps (`websockets==9.1`) in FLAC Python.
+
+## Testing Expectations
+
+- For tool/contract changes, run:
+  - `tests/test_phase2_tools.py`
+  - `tests/test_tool_contracts.py`
+Mock bridge based tests are preferred for deterministic CI.
+
+## Documentation Sources
+
+FLAC searchable docs live under:
+
+- `src/flac_mcp/knowledge/resources/command_docs/`
+- `src/flac_mcp/knowledge/resources/python_sdk_docs/`
+- `src/flac_mcp/knowledge/resources/references/`
+
+When changing schema/content shape, verify browse/query tool behavior remains consistent.
+
+## Commit Style
+
+Use conventional prefixes seen in repository history, for example:
+
+- `feat: ...`
+- `fix: ...`
+- `refactor: ...`
+- `test: ...`
+- `docs: ...`
+
+Keep commit messages focused on why the change was needed.

flac_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to `flac-mcp` are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--
+Add a new section per release before tagging. The publish workflow extracts
+the section matching the tag version and uses it as the GitHub release body.
+The release will fail to publish if no matching entry is found.
+
+## [x.y.z] - YYYY-MM-DD
+
+Description of the release.
+-->
+
+## [0.1.0] - 2026-05-20
+
+Initial release of `flac-mcp`. Scaffolded from `pfc-mcp` 0.3.15: the MCP
+server was renamed (`flac_*` tools, `src/flac_mcp` package) and retargeted
+to the ITASCA FLAC product family (FLAC2D/FLAC3D); the in-product bridge
+runtime was extracted to the standalone `itasca-mcp-bridge` package. The
+bundled command/API/reference knowledge base is inherited from `pfc-mcp`
+and currently covers ITASCA command documentation.
+
+## [0.3.15] - 2026-05-16
+
+Version-aware reference documentation. The `contact-models` reference grows
+from 5 to 22 models (all PFC mechanical + thermal contact models) and
+`pfc_browse_reference` becomes version-aware for PFC 6.0/7.0/9.0.
+
+- `pfc_browse_reference` gains a `version` parameter (6.0/7.0/9.0, default
+  7.0) mirroring `pfc_browse_commands`: the model list is filtered by
+  version availability, requesting a model absent in the target version
+  returns a friendly `item_unavailable_for_version` error (with
+  `available_versions`), and not-found suggestions are version-filtered.
+- New models: arrlinear, bilinear, burger, eepa, fish, flatjoint,
+  hysteretic, jkr, lineardipole, null, smoothjoint, softbond,
+  springnetwork, thermalnull, thermalpipe, plus 9.0-only `mohr` and
+  `subspringnetwork`. The 5 legacy curated models keep their content.
+- Content is shared across versions (measured: 7.0 == 9.0, and 6.0 == 7.0
+  for shared properties), so no per-version data duplication. Differences
+  are encoded as a per-model `availability` map and per-property `since`
+  markers (flatjoint `fj_cohres`/`fj_resmode` since 7.0; softbond
+  `rgap`/`sb_coh`/`sb_fa`/`sb_mcf` since 9.0). `range-elements` and
+  `plot-items` have no `availability` and remain version-agnostic
+  (backward compatible).
+- Property extraction reworked to split on `<dt id="kwd:...">` markers
+  instead of pairing `<dt>/<dd>`, so pages that nest base properties in a
+  child `<dl class="keyword">` (e.g. eepa) no longer bleed text or drop
+  the nested keywords; model-specific properties collapse into a single
+  clean group.
+
+## [0.3.14] - 2026-05-15
+
+Second wave of command documentation expansion: 123 new commands across
+8 new scopes, bringing totals to 21 categories / 362 commands (was 13 / 239).
+
+- `geometry` (34): nodes, edges, polygons, import/export, refinement, tessellation
+- `fracture` (32): DFN — create, generate, intersections, templates, joint-set
+- `table`    (11): numerical x/y tables for boundary conditions and history data
+- `group`     (4): named-group lifecycle (create / list / rename / slot)
+- `trace`     (7): per-object trace recording (lifecycle / export / interval)
+- `project`   (6): GUI project containers (new / save / restore / execute)
+- `data`     (26): user data containers — label/scalar/vector/tensor sub-namespaces
+- `domain`    (3): domain extent, boundary conditions, periodic-cell strain-rate
+
+All entries populated for PFC 6.0/7.0/9.0 (7 commands marked unavailable in
+6.0 as new in later versions; e.g. `fracture intersections` machinery).
+
+Note: the "dfn" doc module is exposed under the scope name `fracture` to
+match the actual command verb users type. Dotted HTML stems (e.g.
+`cmd_geometry.edge.create.html`, `cmd_data.scalar.create.html`) are mapped
+to dash-separated JSON keys (`edge-create`, `scalar-create`) following the
+rblock convention. `parse_pfc{600,700,900}.py` `build_html_map` learned the
+same dot→dash rule.
+
+`range` was considered but not added — the HTML files under
+`range_manual/range_commands/` are syntax reference (rangelogical,
+rangenaming, rangephrase), not commands.
+
+Fixes `pfc_browse_commands` to accept the natural space-separated form
+of compound sub-commands (e.g. `geometry edge create`, `data scalar
+create`, `fracture intersections compute`, `contact cmat add`).
+Previously the lookup only matched the stored dash form (`edge-create`,
+`cmat-add`), forcing users to type a non-PFC-syntax variant.
+
+## [0.3.13] - 2026-05-15
+
+Expands PFC command documentation coverage from 177 to 239 entries
+across 13 categories (was 10). Three new scopes — `program` (28
+commands: license, threads, log, system, lifecycle), `history` (8:
+interval, export, label, results), and `fish` (11: callback, define,
+list, debug, trace) — join filled gaps in `model` (+9: creep,
+dynamic, energy, factor-of-safety, fluid, list, precision, step,
+title), `contact` (+3: extra, history, list), and `fragment` (+3:
+groupisolated, groupslot, map). All entries are populated for PFC
+6.0/7.0/9.0. These commands were previously skipped because their
+Python SDK equivalents return nothing; now that `itasca.command()`
+stdout is captured via the bridge log, exposing them lets agents
+read program/model/history/contact list output through normal
+documentation lookup. A new `bootstrap_missing.py` script under
+`command_docs/` walks the installed PFC HTML manuals and writes
+complete versioned JSON.
+
+Trims trailing float-precision noise from BM25 result scores in
+`pfc_query_command` and `pfc_query_python_api` (e.g.
+`2.4743000000000004` → `2.47`).
+
+## [0.3.12] - 2026-05-14
+
+Surfaces the structured cancellation outcomes from pfc-mcp-bridge >=
+0.3.2 through `pfc_execute_code`: `terminated` (bridge aborted at the
+deadline, partial output returned, PFC state may be partially
+modified), `timeout` with `details.method="stuck_in_c"` (snippet stuck
+in a C extension; bridge may recover when the C call returns),
+`interrupted`, and the default `timeout` path. Local wait widens to
+`timeout_ms / 1000 + 5.0s` so the bridge has room to deliver the
+`terminated` response after its own grace window.
+
+Drops `pfc_mcp.formatting.normalize_status()` (and its re-export from
+`pfc_mcp.tools.task_formatting`); the shim only mapped legacy
+`success`/`error` status from pre-0.3.0 bridges. Requires
+pfc-mcp-bridge >= 0.3.0; pin `pfc-mcp<0.3.12` if you can't upgrade the
+bridge.

flac_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,142 @@
+# CLAUDE.md
+
+Guidance for coding agents working in the `flac-mcp` repository.
+
+## Project Overview
+
+`flac-mcp` provides an MCP server for ITASCA FLAC workflows plus a bridge runtime that runs inside FLAC GUI.
+
+This project spans two runtime contexts:
+
+- `src/flac_mcp/` (Python >= 3.10): MCP server package used by clients/tooling
+- `itasca-mcp-bridge/` (FLAC embedded Python, often 3.6): WebSocket bridge running inside FLAC GUI — a **separate repository** (`yusong652/itasca-mcp-bridge`) vendored here as a git submodule
+
+Treat these as separate deployment targets with independent release cycles.
+
+## Core Architecture
+
+### MCP side (`src/flac_mcp`)
+
+- Exposes documentation tools and execution tools through FastMCP
+- Communicates with bridge via WebSocket client (`flac_mcp.bridge.client`)
+- Returns a unified tool envelope: `ok`, `data`, `error`
+- Dual execution model: synchronous REPL (`flac_execute_code`) for quick queries, script-first async (`flac_execute_task` + `flac_check_task_status`) for long-running simulations
+
+### Bridge side (`itasca-mcp-bridge`)
+
+- Runs in FLAC GUI process
+- Owns thread-safe interaction with ITASCA SDK
+- Handles long-running tasks and diagnostics
+- Must be started from FLAC GUI (for example with `%run .../itasca-mcp-bridge/start_bridge.py`)
+
+## Repository Layout
+
+```text
+flac-mcp/
+├── src/flac_mcp/
+│   ├── bridge/          # MCP-side bridge client/task manager
+│   ├── knowledge/       # command/API/reference search system
+│   ├── tools/           # MCP tool implementations
+│   ├── formatting.py    # shared response formatting
+│   └── server.py        # MCP server entrypoint
+├── itasca-mcp-bridge/      # git submodule → separate repo; runtime executed inside FLAC GUI
+└── tests/               # MCP/tool contract tests
+```
+
+## Development Commands
+
+Run from repository root.
+
+```bash
+uv sync
+uv sync --group dev
+uv run flac-mcp
+uv run pytest tests/test_phase2_tools.py
+uv run pytest tests/test_tool_contracts.py
+```
+
+## Engineering Rules
+
+1. Keep MCP and bridge concerns separate.
+   - Do not couple MCP logic to FLAC GUI internals.
+   - Do not introduce application/session policy into bridge runtime.
+
+2. Preserve execution semantics for each model.
+   - `flac_execute_code` runs synchronous snippets and returns stdout/result immediately.
+   - `flac_execute_task` submits scripts and returns quickly.
+   - Progress/result retrieval goes through `flac_check_task_status`.
+
+3. Maintain structured tool contracts.
+   - Prefer stable machine-readable keys over ad-hoc text parsing.
+   - Use the unified envelope for all tool business payloads:
+     - success: `{"ok": true, "data": ...}`
+     - error: `{"ok": false, "error": {"code": str, "message": str, "details"?: object}}`
+   - Enforce coherence: `ok=true` must not include `error`; `ok=false` must include `error`.
+   - Do not require duplicate presentation fields (for example, `display`) when they mirror structured data.
+   - Let clients render human-facing formatting from structured fields.
+   - Documentation tools must keep `data` consistent as:
+     - `source`: `"commands" | "python_api" | "reference"`
+     - `action`: `"browse" | "query"`
+     - `entries`: `list[object]`
+     - `summary`: `object` (counts/hints/context)
+   - Keep query/path/input echo minimal; prefer putting necessary context in `summary` or `error.details.input`.
+
+4. Keep compatibility when practical.
+   - If moving shared helpers, keep thin compatibility re-exports when tests or downstream code rely on old import paths.
+
+5. Respect runtime constraints.
+   - MCP package uses modern deps (`websockets>=15`).
+   - Bridge side may require legacy-compatible deps (`websockets==9.1`) in FLAC Python.
+
+## Testing Expectations
+
+- For tool/contract changes, run:
+  - `tests/test_phase2_tools.py`
+  - `tests/test_tool_contracts.py`
+Mock bridge based tests are preferred for deterministic CI.
+
+## Documentation Sources
+
+FLAC searchable docs live under:
+
+- `src/flac_mcp/knowledge/resources/command_docs/`
+- `src/flac_mcp/knowledge/resources/python_sdk_docs/`
+- `src/flac_mcp/knowledge/resources/references/`
+
+When changing schema/content shape, verify browse/query tool behavior remains consistent.
+
+## Release Process
+
+The two packages live in **separate repositories** and release independently via GitHub Actions on tag push (PyPI Trusted Publishing — OIDC, no tokens).
+
+| Package | Repo | Tag pattern | Workflow | Version file | PyPI environment |
+|---------|------|-------------|----------|--------------|------------------|
+| `flac-mcp` | `yusong652/flac-mcp` (this repo) | `v*` (e.g. `v0.1.0`) | `.github/workflows/publish.yml` | `src/flac_mcp/__init__.py` | `pypi` |
+| `itasca-mcp-bridge` | `yusong652/itasca-mcp-bridge` (submodule) | `v*` (e.g. `v0.1.0`) | `.github/workflows/publish.yml` | `src/itasca_mcp_bridge/__init__.py` | `pypi` |
+
+Steps to release `flac-mcp` (run in this repo):
+
+1. Bump `__version__` in `src/flac_mcp/__init__.py` (hatch dynamic versioning — single source of truth).
+2. Add a matching `## [x.y.z]` entry to `CHANGELOG.md` (the publish workflow hard-fails without it).
+3. Commit and push to `main`.
+4. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+
+Releasing `itasca-mcp-bridge` follows the same steps **inside its own repository** (`yusong652/itasca-mcp-bridge`), not from here.
+
+The `flac-mcp` publish workflow runs tests before publishing; the bridge workflow publishes directly.
+
+**Important**: the tag version and the `__version__` in `__init__.py` must match. PyPI rejects uploads for versions that already exist.
+
+CI also runs on every push/PR to `main` (`.github/workflows/test.yml`): ruff check, ruff format, mypy, and pytest with coverage.
+
+## Commit Style
+
+Use conventional prefixes seen in repository history, for example:
+
+- `feat: ...`
+- `fix: ...`
+- `refactor: ...`
+- `test: ...`
+- `docs: ...`
+
+Keep commit messages focused on why the change was needed.

flac_mcp-0.1.0/GEMINI.md

@@ -0,0 +1,117 @@
+# GEMINI.md
+
+Guidance for coding agents working in the `flac-mcp` repository.
+
+## Project Overview
+
+`flac-mcp` provides an MCP server for ITASCA FLAC workflows plus a bridge runtime that runs inside FLAC GUI.
+
+This repository intentionally has two runtime contexts:
+
+- `src/flac_mcp/` (Python >= 3.10): MCP server package used by clients/tooling
+- `itasca-mcp-bridge/` (FLAC embedded Python, often 3.6): WebSocket bridge running inside FLAC GUI
+
+Treat these as separate deployment targets even though they live in one repository.
+
+## Core Architecture
+
+### MCP side (`src/flac_mcp`)
+
+- Exposes documentation tools and execution tools through FastMCP
+- Communicates with bridge via WebSocket client (`flac_mcp.bridge.client`)
+- Returns a unified tool envelope: `ok`, `data`, `error`
+- Uses script-first execution model (`flac_execute_task` + `flac_check_task_status`)
+
+### Bridge side (`itasca-mcp-bridge`)
+
+- Runs in FLAC GUI process
+- Owns thread-safe interaction with ITASCA SDK
+- Handles long-running tasks and diagnostics
+- Must be started from FLAC GUI (for example with `%run .../itasca-mcp-bridge/start_bridge.py`)
+
+## Repository Layout
+
+```text
+flac-mcp/
+├── src/flac_mcp/
+│   ├── bridge/          # MCP-side bridge client/task manager
+│   ├── knowledge/       # command/API/reference search system
+│   ├── tools/           # MCP tool implementations
+│   ├── formatting.py    # shared response formatting
+│   └── server.py        # MCP server entrypoint
+├── itasca-mcp-bridge/      # runtime executed inside FLAC GUI
+└── tests/               # MCP/tool contract tests
+```
+
+## Development Commands
+
+Run from repository root.
+
+```bash
+uv sync
+uv sync --group dev
+uv run flac-mcp
+uv run pytest tests/test_phase2_tools.py
+uv run pytest tests/test_tool_contracts.py
+```
+
+## Engineering Rules
+
+1. Keep MCP and bridge concerns separate.
+   - Do not couple MCP logic to FLAC GUI internals.
+   - Do not introduce application/session policy into bridge runtime.
+
+2. Preserve script-only execution semantics.
+   - `flac_execute_task` submits scripts and returns quickly.
+   - Progress/result retrieval goes through `flac_check_task_status`.
+
+3. Maintain structured tool contracts.
+   - Prefer stable machine-readable keys over ad-hoc text parsing.
+   - Use the unified envelope for all tool business payloads:
+     - success: `{"ok": true, "data": ...}`
+     - error: `{"ok": false, "error": {"code": str, "message": str, "details"?: object}}`
+   - Enforce coherence: `ok=true` must not include `error`; `ok=false` must include `error`.
+   - Do not require duplicate presentation fields (for example, `display`) when they mirror structured data.
+   - Let clients render human-facing formatting from structured fields.
+   - Documentation tools must keep `data` consistent as:
+     - `source`: `"commands" | "python_api" | "reference"`
+     - `action`: `"browse" | "query"`
+     - `entries`: `list[object]`
+     - `summary`: `object` (counts/hints/context)
+   - Keep query/path/input echo minimal; prefer putting necessary context in `summary` or `error.details.input`.
+
+4. Keep compatibility when practical.
+   - If moving shared helpers, keep thin compatibility re-exports when tests or downstream code rely on old import paths.
+
+5. Respect runtime constraints.
+   - MCP package uses modern deps (`websockets>=15`).
+   - Bridge side may require legacy-compatible deps (`websockets==9.1`) in FLAC Python.
+
+## Testing Expectations
+
+- For tool/contract changes, run:
+  - `tests/test_phase2_tools.py`
+  - `tests/test_tool_contracts.py`
+Mock bridge based tests are preferred for deterministic CI.
+
+## Documentation Sources
+
+FLAC searchable docs live under:
+
+- `src/flac_mcp/knowledge/resources/command_docs/`
+- `src/flac_mcp/knowledge/resources/python_sdk_docs/`
+- `src/flac_mcp/knowledge/resources/references/`
+
+When changing schema/content shape, verify browse/query tool behavior remains consistent.
+
+## Commit Style
+
+Use conventional prefixes seen in repository history, for example:
+
+- `feat: ...`
+- `fix: ...`
+- `refactor: ...`
+- `test: ...`
+- `docs: ...`
+
+Keep commit messages focused on why the change was needed.

flac_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusong Han
+
+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.