feat(mcp): Zero-Schema-Tax MCP Client Bridge & Hierarchical JIT --help Discovery

Open
  • Is something wrong?
#8 0 comments 0 reactions 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
python
Domain
ai, backend, cli

Research direction

Start with the architecture blog post linked in the issue, then inspect the existing toolbox index, command dispatch, and ACT_TOOL_SCHEMA entry points to see how MCP discovery would fit. The issue names tether/mcp.py for the client; check the project’s dependency setup and tests before choosing the transport details. Done means the acceptance criteria pass, including one toolbox line per server, hierarchical help for large tool sets, and only ACT_TOOL_SCHEMA exposed to the model.

Written by the indexing model from the issue text.

Description

enhancement

Summary & Motivation

As described in the Tether architecture blog post ("What Tether is still missing: 1. MCP support, without the schema tax"):

"A lot of useful integrations already ship as MCP servers, and I want them. But the usual way of plugging MCP into a harness is exactly the thing that started this project: every server dumps its full tool list and JSON schemas into the prompt up front. The version I want keeps the act(cmd, stdin) rule. An MCP server would show up as one line in the toolbox index (github : Issues and pull requests), and its tools would be discovered just in time, with github --help and github issue create --help, like any other command. The protocol stays on the outside of the envelope and the model never sees a schema it did not ask for. The hard part is the discovery step: a server with 80 tools needs a good --help hierarchy, or I have rebuilt the problem one level down."

Literature & State-of-the-Art Grounding

  1. Performance Degradation from Tool Schema Bloat:
    • Qin et al. (ICLR 2024), "ToolLLM: Facilitating Large Language Models to Master 16000+ Real-World APIs" (arXiv:2307.16789): Shows that dumping >10–20 API schemas directly into an LLM context window causes severe attention dilution and argument hallucination; hierarchical retrieval/routing is required.
    • Patil et al. (NeurIPS 2024), "Gorilla: Large Language Model Connected with Massive APIs" (arXiv:2305.15334): Demonstrates that separating API discovery from API invocation prevents syntax hallucinations on smaller models.
  2. Hierarchical CLI Progressive Disclosure (ACI):
    • Yang et al. (NeurIPS 2024), "SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering" (arXiv:2405.15793) & Wang et al. (ICML 2024), "CodeAct" (arXiv:2402.01030): Unifying tool execution behind a single POSIX-like command channel with concise, progressive --help feedback preserves small-model reasoning capacity.

State-of-the-Art Fix & Architecture Design

1. Zero-Dependency JSON-RPC 2.0 MCP Client (tether/mcp.py)

In accordance with Rule 7 (Zero Framework Bloat), implement a thin, stdlib/httpx JSON-RPC 2.0 client supporting:

  • Stdio transport: asyncio.create_subprocess_exec communicating over newline-delimited JSON-RPC (initialize, tools/list, tools/call).
  • HTTP/SSE transport: httpx.AsyncClient for remote MCP endpoints.
  • Security Envelope (Rule 6): Scrub secret environment variables from stdio MCP subprocesses unless explicitly whitelisted in the server config.
2. Two-Level Hierarchical --help Compiler for Large MCP Servers (Solving the 80-Tool Problem)

When an MCP server exposes $N$ tools (e.g., github_create_issue, github_list_issues, github_merge_pr, ...):

  1. Level 0 (System Prompt Toolbox Index — $\le 12$ tokens):
    The entire MCP server appears as one single line in toolbox_index(): 
    github : GitHub MCP server (issues, pulls, repos, search)
  2. Level 1 (act("github --help") — Prefix Grouping / Sub-Namespace Tree, $\le 60$ tokens):
    • If the server has $\le 8$ tools, list <subcmd> : <1-line summary> directly.
    • If the server has $> 8$ tools (e.g., 80 tools), automatically split tool names on _ / - common prefixes (issue, pull, repo, search) or support github --help <filter_keyword> so github --help never dumps 80 lines at once: 
      Usage: github <group|tool> [args...] | github --help [group|keyword]
Groups: issue (12), pull (9), repo (15), actions (8), search (5)
  3. Level 2 (act("github issue create --help") — JIT JSON-Schema-to-CLI Compiler, $\le 60$ tokens):
    • Deterministically compiles the MCP tool's inputSchema (JSON Schema properties, types, required flags) into Tether's compact POSIX flag signature: 
      Usage: github issue create --repo <str> --title <str> [--labels <list>] [stdin: body]
    • Automatically maps large string/markdown properties (body, content, patch, code) to stdin (Rule 2) while also accepting --body flags.
3. Acceptance Criteria
  • Static system prompt increases by at most 1 line ($\le 12$ tokens) per enabled MCP server, regardless of whether the server has 5 or 100 tools (Rule 1 & Rule 4).
  • ACT_TOOL_SCHEMA remains the only JSON tool schema sent to the LLM provider (Rule 2).
  • Zero heavy SDK dependencies added (mcp SDK not required; pure asyncio stdio + httpx JSON-RPC 2.0).
Dominant language
Python
Stars
3
Forks
1
Avg merge
52m
Merged PRs (30d)
166

Getting set up

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 igormcsouza/tether

All issues in igormcsouza/tether

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.