Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Proposal: add discovery schemas for five audio tools

Open
  • Is something wrong?
#1,527 2 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
csharp
Domain
api, backend

Research direction

Start with src/OpenClaw.Shared/Mcp/McpToolBridge.cs and the existing command constants and parser behavior in NodeCapabilities.cs, SttCapability.cs, and TtsCapability.cs. Review the proposed McpAudioToolSchemas.cs and tests/OpenClaw.Shared.Tests/McpAudioToolSchemaTests.cs, then run the focused and full suites. Done means the five schemas match the documented acceptance criteria without changing dispatch, parsing, errors, results, or unrelated tool schemas.

Written by the indexing model from the issue text.

Description

clawsweeper:needs-maintainer-review clawsweeper:needs-product-decision clawsweeper:no-new-fix-pr clawsweeper:source-repro impact:ux-friction issue-rating: 🦞 diamond lobster P2 stale

The five existing audio tools advertise empty, permissive input schemas. Their descriptions explain arguments, but clients cannot discover required fields and useful defaults from inputSchema.

I implemented a small discovery-only pilot for stt.transcribe, stt.listen, stt.status, tts.speak and tts.status on my fork's proposal/mcp-audio-tool-schemas branch. It adds no dependency or runtime validation. The focused checks and required local test suites pass; the full repository build is still blocked at WinUI's existing npm dependency download. This is a proposal for review, not a merge-ready claim.

Existing work

This is not a newly discovered gap. #355 was closed as consolidated, not necessarily fixed, into the MCP hardening work associated with #372. That tracker was later closed in favor of the project board's Scenarios view/Mission field. Both are historical references, not a claim about current tracking or shipped behavior.

#401, Add typed MCP tool input schemas, was closed unmerged, with fresh post-refactor review and implementation requested. This pilot does not revive its broader all-command catalog or opt-in runtime validation.

Concrete example

At inspected base 273b0182745a3093c0e09f306ca8a1fff6ef3c5a, the bridge advertises an empty permissive object for every command. The current upstream bridge and audio parser file blobs still match this tested baseline.

For example, stt.transcribe changes from:

{"type":"object","additionalProperties":true,"properties":{}}

to the following structure (descriptions omitted here):

{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "maxDurationMs": {"type": "integer", "minimum": 1, "maximum": 30000},
    "language": {"examples": ["en-US", "auto"]}
  },
  "required": ["maxDurationMs"]
}

The complete captured before and after responses show all five actual registry names. Only their schemas change; descriptions and other catalog fields stay identical.

Keep the current parser contract

The argument helpers, STT handlers and TTS parser/provider policy are more permissive than a conventional strict schema:

Input Preserve this behavior
stt.transcribe.maxDurationMs Required positive Int32, at most 30000. JSON Schema accepts 5000.0/5e3 as mathematical integers; the parser rejects those token forms. Describe that limitation.
stt.listen.timeoutMs Default 30000; Int32 values clamp to 1000..120000, not reject. Wrong types and unreadable numbers select the default.
STT language Trimmed limited language/script/region pattern or case-insensitive auto. Blank/null/non-string acts omitted. Transcribe uses configured language; listen uses auto.
tts.speak.text Required string, trimmed before nonblank and 5000 UTF-16-code-unit checks. A raw maxLength would reject padded valid text and count Unicode differently.
TTS options Strings trim; blank/null/non-string selects settings. Provider case is normalized by the service. Nonblank explicit provider requests stay strict. Only literal JSON true enables interrupt.

Every schema retains additionalProperties: true. Optional fallback fields omit strict types. Provider names are examples, not a case-sensitive enum. Defaults are annotations, not bridge coercion. The schema does not guarantee permission, provider readiness or call success. Unknown provider names still reach the existing service error path.

Small implementation steps

  1. Add the focused metadata helper using existing command constants and System.Text.Json anonymous-object conventions.
  2. Select that metadata inside HandleToolsList; preserve the original generic fallback for every other command. Do not change capability registration, dispatch, errors or results.
  3. Add real-bridge characterization and schema tests with fake audio handlers. Update MCP and winnode guidance with coercion and schema limitations.
  4. Review this five-tool slice before expanding the catalog. No SDK, audio-provider, transport or result-format refactor is required.

Alternatives are to retain description-only discovery, make a separate behavioral breaking change toward strict inputs, or build a broader all-command schema system. The pilot avoids coupling those larger choices to exposing information the existing parsers already define.

Acceptance criteria and evidence

  • All five existing names expose the expected properties, required fields and default annotations. Disabled capabilities remain absent; unrelated tools retain their generic schema.
  • Real bridge/capability calls preserve accepted inputs, error strings, clamping, optional coercion, provider policy and existing output casing.
  • All five public schemas are exercised with an existing validator, with mismatches between schema acceptance and parser success explicitly documented.
  • Required local suites report real nonzero test inventories; build and product-proof gaps remain visible.

The same harness blob, 8ec3c9379dc2f132b258f3908d81249427ffd634, ran on B (base production code plus harness) and C (candidate). B ran 75 characterization cases; C also ran the six assertions that require the new schema.

Check Result
Baseline characterization 75 passed, 0 failed, 0 skipped
Candidate focused suite 202 passed, 0 failed, 0 skipped: 81 new-schema/characterization, 47 bridge, 42 STT, 32 TTS
Five schemas, existing Test-Json validator 21/21 expected acceptance outcomes matched, including disclosed caveats
Full Shared suite, final 4188 passed, 0 failed, 32 existing opt-in integration skips
Full Tray suite, final 3072 passed, 0 failed, 0 skipped
Full WinNode CLI suite 127 passed, 0 failed, 0 skipped
Required full build Exit 1: existing node-pty npm TLS download failure in WinUI

Seven before-call pairs and after-call pairs are identical: five successes and two parser errors. These are representative in-process JSON-RPC calls through the actual bridge and capabilities, not HTTP or real audio proof. Handler results are deliberately synthetic, including TTS result propagation; strict provider selection is checked separately against the existing policy.

Validator outcomes identify PowerShell 7.6.6 and JsonSchema.Net 7.0.0.0. Draft 2020-12 is selected only for validation, not added to wire output. Whitespace-only/overlong TTS text and decimal/exponent transcribe tokens illustrate why schema acceptance is not equivalent to a successful call.

Reproduction and remaining gaps

The evidence guide includes commands, environment isolation, requirement-to-test mapping and failure history. Exact command arrays, exit codes and counters, method inventories and SHA-256 manifest are available in documentation-only evidence commit 17db0e3bf194fbf54dabe281bf2950e361c0ae0b. It preserves C's production and test trees.

The initial Tray run had 3071 passes and one failure from an app-local VC runtime missing in the incomplete WinUI output. A first copy-target attempt used the wrong platform output path; its focused rerun still had three passes and one failure. Matching the existing target to the actual build directory repaired the environment, after which all 3072 Tray tests passed. Both failed attempts remain recorded. No test weakening or source fix was needed; this does not turn the blocked full build into success.

Structured autoreview was attempted once but could not start its missing codex executable. Direct source review found no actionable in-scope issue; there is no clean structured-review claim. Running WinUI/HTTP MCP, gateway invocation, real audio providers and ecosystem-wide client compatibility remain unverified. No agent-success percentage or performance improvement is claimed.

I can put up a PR if there is interest.

Dominant language
C#
Stars
2.1k
Forks
315
Avg merge
2d 1h
Merged PRs (30d)
127

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openclaw/openclaw-windows-node

All issues in openclaw/openclaw-windows-node

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.