mcp-sieve 0.1.0__tar.gz

mcp_sieve-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env
+*.log
+
+# Real config with local paths — use config.example.yaml as template
+config.yaml

mcp_sieve-0.1.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+Для операций с Git, веб-скрапинга и работы с файлами всегда используй инструменты mcp-sieve через mcp_router_call, так как они возвращают структурированный и чистый вывод.
+
+Для удобного поиска по репозиториям есть Gitmcp.

mcp_sieve-0.1.0/LICENSE

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

mcp_sieve-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: mcp-sieve
+Version: 0.1.0
+Summary: MCP Sieve — semantic tool selection proxy for LLMs. Aggregates downstream MCP servers into 2 static tools (select + call) via Ollama embeddings.
+Project-URL: Homepage, https://github.com/dimarch0x/mcp-sieve
+Project-URL: Repository, https://github.com/dimarch0x/mcp-sieve
+Project-URL: Issues, https://github.com/dimarch0x/mcp-sieve/issues
+Author: dimarch0x
+License: MIT License
+        
+        Copyright (c) 2026 dimarch0x
+        
+        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.
+License-File: LICENSE
+Keywords: llm,mcp,mcp-server,ollama,semantic-routing,tool-selection
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# MCP Sieve
+
+A semantic proxy for MCP servers. Solves **tool selection degradation** — when an LLM has too many tools, it picks the wrong ones.
+
+The sieve sits between the client (Claude Code, Hermes, any MCP client) and downstream MCP servers. The client sees **2 tools** instead of dozens: `mcp_router_select` + `mcp_router_call`. The first finds relevant tools via embeddings, the second proxies the call.
+
+## How it works
+
+```
+Client (Claude Code / Hermes)
+  ↓ sees only 2 tools
+mcp_router_select(task="...")  →  embeddings → top-N relevant tools
+mcp_router_call(tool_name, arguments)  →  proxies to downstream
+  ↓
+downstream MCP servers (time, fetch, git, arxiv, playwright, ...)
+```
+
+**Two call paths:**
+
+1. **Path 1 (notifications/tools/list_changed):** `select` finds tools → sieve updates `tools/list` → client calls tools directly. Works with clients that support dynamic toolset updates.
+
+2. **Path 2 (mcp_router_call proxy):** for clients with a **frozen toolset** (Hermes, Claude Code with prompt caching). `select` returns tools with `inputSchema` → `call` proxies execution. No `/reset` needed when new downstream tools are discovered.
+
+## Install
+
+```bash
+git clone <repo> ~/Projects/mcp-sieve
+cd ~/Projects/mcp-sieve
+uv pip install -e .
+```
+
+Requires [Ollama](https://ollama.com) with an embed model:
+```bash
+ollama pull nomic-embed-text
+```
+
+## Quick start
+
+Copy the example config and edit it:
+```bash
+cp config.example.yaml config.yaml
+# edit config.yaml — add your downstream servers and paths
+```
+
+Run standalone:
+```bash
+python -m mcp_router.server
+```
+Server listens on stdio (JSON-RPC).
+
+## Connect to Claude Code
+
+In `~/.claude.json` → `projects["<path>"].mcpServers`:
+
+```json
+"sieve": {
+  "type": "stdio",
+  "command": "uvx",
+  "args": ["--from", "/path/to/mcp-sieve", "mcp-sieve"],
+  "env": {
+    "MCP_ROUTER_CONFIG": "/path/to/mcp-sieve/config.yaml"
+  }
+}
+```
+
+Or via CLI:
+```bash
+claude mcp add sieve -- uvx --from /path/to/mcp-sieve mcp-sieve
+```
+
+> **Windows:** `MCP_ROUTER_CONFIG` is required — `uvx` installs the package into an isolated venv, `__file__` points into uv-cache. See [Windows notes](#windows-notes) below.
+
+## Connect to Hermes
+
+```bash
+hermes mcp add sieve --command uvx --args "--from" --args "/path/to/mcp-sieve" --args "mcp-sieve"
+hermes mcp test sieve
+# /reset in chat
+```
+
+## Config
+
+`config.yaml` (see `config.example.yaml` for a full template):
+
+```yaml
+downstream:
+  - name: time
+    command: uvx
+    args: ["mcp-server-time"]
+
+  - name: fetch
+    command: uvx
+    args: ["mcp-server-fetch"]
+
+  - name: git
+    command: uvx
+    args: ["mcp-server-git", "--repository", "/path/to/your/repo"]
+
+  # Windows: npx is a .cmd file — needs cmd /c
+  - name: context7
+    command: cmd
+    args: ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
+
+  - name: filesystem
+    command: cmd
+    args: ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+
+  # Remote MCP over HTTP (streamable) or SSE — no local process.
+  # transport defaults to stdio; a bare url implies http.
+  - name: gitmcp
+    transport: http
+    url: "https://gitmcp.io/docs"
+
+embeddings:
+  ollama_url: "http://127.0.0.1:11434/api/embeddings"
+  model: "nomic-embed-text"
+  top_n: 10
+```
+
+Env variables:
+- `MCP_ROUTER_CONFIG` — path to `config.yaml` (otherwise looks in CWD or next to source)
+- `MCP_SIEVE_DOWNSTREAM_<N>_NAME` / `_COMMAND` / `_ARGS` / `_URL` / `_TRANSPORT` — define downstream servers without a file (Docker/k8s). `N` starts at 1, stops at the first gap. `_ARGS` is a JSON array or whitespace-split. A same-named entry overrides the yaml one.
+- `MCP_SIEVE_OLLAMA_URL` / `MCP_SIEVE_EMBED_MODEL` / `MCP_SIEVE_TOP_N` — embeddings overrides
+
+Crashed downstream servers (Ollama, npx) auto-reconnect with exponential backoff — no restart needed.
+
+## Windows notes
+
+1. **npx → `cmd /c npx`:** `npx` is a `.cmd` file, Python subprocess (MCP SDK) can't find it without a shell. `uvx` is a real binary, works directly.
+
+2. **uvx --from and dependencies:** `uvx --from <project>` installs the package into an isolated uv-cache venv. All imports must be in `pyproject.toml` `[project.dependencies]` — implicit deps from the dev env won't be picked up.
+
+3. **uv cache clean:** if the cache is locked (`os error 32`), kill MCP server processes first:
+   ```bash
+   powershell -Command "Get-Process | Where-Object { $_.ProcessName -match 'mcp|uv' } | Stop-Process -Force"
+   uv cache clean --force
+   ```
+
+4. **Debug connection failures:** `claude --debug` writes to `~/.claude/debug/<session>.txt`. Grep `Server stderr:` for real server tracebacks.
+
+## Stack
+
+- **MCP Python SDK** (`mcp`) — stdio + HTTP/SSE transports, `notifications/tools/list_changed`
+- **Ollama** — local embeddings (`nomic-embed-text`), free
+- **numpy** — cosine similarity
+- **httpx** — HTTP client for Ollama API
+
+## Fallback
+
+If Ollama is unavailable — the sieve doesn't crash. `mcp_router_select` returns **all** downstream tools without ranking, with a warning in the response.
+
+## Performance
+
+Tested with 9 downstream servers (74 tools):
+- `mcp_router_select`: 83–166ms
+- `mcp_router_call`: 15–774ms (longest: playwright browser navigation)
+- Startup: ~16s (all 9 downstream connect + 74 embeddings built)
+
+## Status
+
+Working end-to-end in Claude Code and Hermes. See `TASKS.md` for the roadmap and benchmark results.

mcp_sieve-0.1.0/README.md

@@ -0,0 +1,161 @@
+# MCP Sieve
+
+A semantic proxy for MCP servers. Solves **tool selection degradation** — when an LLM has too many tools, it picks the wrong ones.
+
+The sieve sits between the client (Claude Code, Hermes, any MCP client) and downstream MCP servers. The client sees **2 tools** instead of dozens: `mcp_router_select` + `mcp_router_call`. The first finds relevant tools via embeddings, the second proxies the call.
+
+## How it works
+
+```
+Client (Claude Code / Hermes)
+  ↓ sees only 2 tools
+mcp_router_select(task="...")  →  embeddings → top-N relevant tools
+mcp_router_call(tool_name, arguments)  →  proxies to downstream
+  ↓
+downstream MCP servers (time, fetch, git, arxiv, playwright, ...)
+```
+
+**Two call paths:**
+
+1. **Path 1 (notifications/tools/list_changed):** `select` finds tools → sieve updates `tools/list` → client calls tools directly. Works with clients that support dynamic toolset updates.
+
+2. **Path 2 (mcp_router_call proxy):** for clients with a **frozen toolset** (Hermes, Claude Code with prompt caching). `select` returns tools with `inputSchema` → `call` proxies execution. No `/reset` needed when new downstream tools are discovered.
+
+## Install
+
+```bash
+git clone <repo> ~/Projects/mcp-sieve
+cd ~/Projects/mcp-sieve
+uv pip install -e .
+```
+
+Requires [Ollama](https://ollama.com) with an embed model:
+```bash
+ollama pull nomic-embed-text
+```
+
+## Quick start
+
+Copy the example config and edit it:
+```bash
+cp config.example.yaml config.yaml
+# edit config.yaml — add your downstream servers and paths
+```
+
+Run standalone:
+```bash
+python -m mcp_router.server
+```
+Server listens on stdio (JSON-RPC).
+
+## Connect to Claude Code
+
+In `~/.claude.json` → `projects["<path>"].mcpServers`:
+
+```json
+"sieve": {
+  "type": "stdio",
+  "command": "uvx",
+  "args": ["--from", "/path/to/mcp-sieve", "mcp-sieve"],
+  "env": {
+    "MCP_ROUTER_CONFIG": "/path/to/mcp-sieve/config.yaml"
+  }
+}
+```
+
+Or via CLI:
+```bash
+claude mcp add sieve -- uvx --from /path/to/mcp-sieve mcp-sieve
+```
+
+> **Windows:** `MCP_ROUTER_CONFIG` is required — `uvx` installs the package into an isolated venv, `__file__` points into uv-cache. See [Windows notes](#windows-notes) below.
+
+## Connect to Hermes
+
+```bash
+hermes mcp add sieve --command uvx --args "--from" --args "/path/to/mcp-sieve" --args "mcp-sieve"
+hermes mcp test sieve
+# /reset in chat
+```
+
+## Config
+
+`config.yaml` (see `config.example.yaml` for a full template):
+
+```yaml
+downstream:
+  - name: time
+    command: uvx
+    args: ["mcp-server-time"]
+
+  - name: fetch
+    command: uvx
+    args: ["mcp-server-fetch"]
+
+  - name: git
+    command: uvx
+    args: ["mcp-server-git", "--repository", "/path/to/your/repo"]
+
+  # Windows: npx is a .cmd file — needs cmd /c
+  - name: context7
+    command: cmd
+    args: ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
+
+  - name: filesystem
+    command: cmd
+    args: ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+
+  # Remote MCP over HTTP (streamable) or SSE — no local process.
+  # transport defaults to stdio; a bare url implies http.
+  - name: gitmcp
+    transport: http
+    url: "https://gitmcp.io/docs"
+
+embeddings:
+  ollama_url: "http://127.0.0.1:11434/api/embeddings"
+  model: "nomic-embed-text"
+  top_n: 10
+```
+
+Env variables:
+- `MCP_ROUTER_CONFIG` — path to `config.yaml` (otherwise looks in CWD or next to source)
+- `MCP_SIEVE_DOWNSTREAM_<N>_NAME` / `_COMMAND` / `_ARGS` / `_URL` / `_TRANSPORT` — define downstream servers without a file (Docker/k8s). `N` starts at 1, stops at the first gap. `_ARGS` is a JSON array or whitespace-split. A same-named entry overrides the yaml one.
+- `MCP_SIEVE_OLLAMA_URL` / `MCP_SIEVE_EMBED_MODEL` / `MCP_SIEVE_TOP_N` — embeddings overrides
+
+Crashed downstream servers (Ollama, npx) auto-reconnect with exponential backoff — no restart needed.
+
+## Windows notes
+
+1. **npx → `cmd /c npx`:** `npx` is a `.cmd` file, Python subprocess (MCP SDK) can't find it without a shell. `uvx` is a real binary, works directly.
+
+2. **uvx --from and dependencies:** `uvx --from <project>` installs the package into an isolated uv-cache venv. All imports must be in `pyproject.toml` `[project.dependencies]` — implicit deps from the dev env won't be picked up.
+
+3. **uv cache clean:** if the cache is locked (`os error 32`), kill MCP server processes first:
+   ```bash
+   powershell -Command "Get-Process | Where-Object { $_.ProcessName -match 'mcp|uv' } | Stop-Process -Force"
+   uv cache clean --force
+   ```
+
+4. **Debug connection failures:** `claude --debug` writes to `~/.claude/debug/<session>.txt`. Grep `Server stderr:` for real server tracebacks.
+
+## Stack
+
+- **MCP Python SDK** (`mcp`) — stdio + HTTP/SSE transports, `notifications/tools/list_changed`
+- **Ollama** — local embeddings (`nomic-embed-text`), free
+- **numpy** — cosine similarity
+- **httpx** — HTTP client for Ollama API
+
+## Fallback
+
+If Ollama is unavailable — the sieve doesn't crash. `mcp_router_select` returns **all** downstream tools without ranking, with a warning in the response.
+
+## Performance
+
+Tested with 9 downstream servers (74 tools):
+- `mcp_router_select`: 83–166ms
+- `mcp_router_call`: 15–774ms (longest: playwright browser navigation)
+- Startup: ~16s (all 9 downstream connect + 74 embeddings built)
+
+## Status
+
+Working end-to-end in Claude Code and Hermes. See `TASKS.md` for the roadmap and benchmark results.

mcp_sieve-0.1.0/TASKS.md

@@ -0,0 +1,34 @@
+# Roadmap — MCP Sieve
+
+## Completed
+
+- **Core MCP server** — stdio transport, `initialize`/`tools/list`/`tools/call`, `listChanged` capability
+- **Downstream discovery** — connects to all downstream MCP servers from `config.yaml`, pulls tools via `list_tools()`, one failing server doesn't crash the rest
+- **Semantic search** — Ollama embeddings (`nomic-embed-text`), cosine similarity, top-N ranking. Fallback: if Ollama is down, returns all tools with a warning
+- **Call routing** — `tools/call` proxied to the correct downstream. Unknown tools → clear error
+- **`mcp_router_call` proxy** — for clients with frozen toolsets (prompt caching). `select` returns tools with `inputSchema`, `call` proxies execution. No `/reset` needed on new downstream tools
+- **Cross-platform** — tested on Windows (npx via `cmd /c`, config discovery via `MCP_ROUTER_CONFIG` env). Works with Claude Code and Hermes
+- **HTTP/SSE downstream transport** — `transport: http|sse` + `url` in config connects remote MCP (GitMCP, Cloudflare Remote MCP). stdio stays the default
+- **Env-var config** — `MCP_SIEVE_DOWNSTREAM_<N>_*` and embeddings overrides, for Docker/k8s with no config file. Merges over yaml by name
+- **Auto-reconnect** — per-downstream supervisor tasks with `send_ping` liveness + exponential backoff. A crashed downstream (Ollama, npx) self-heals instead of being lost until restart
+
+## Benchmark
+
+Tested with **10 downstream servers (79 tools)** in Claude Code across 5 long tasks:
+
+| Metric | Result |
+|--------|--------|
+| `mcp_router_select` latency | 83–166ms |
+| `mcp_router_call` latency | 15–774ms |
+| Startup (10 servers + 79 embeddings) | ~16–18s |
+| Tools in LLM system prompt | 2 (always) |
+| Router accuracy (relevant tool in top-10) | 100% across test tasks |
+| Remote HTTP transport | verified (GitMCP via streamable_http) |
+
+**Downstream servers tested:** time, fetch, git, arxiv, context7, filesystem, playwright, sequential-thinking, memory, gitmcp (HTTP)
+
+**Observation:** Claude Code prefers native tools when they overlap (Bash vs git MCP, Write vs filesystem MCP). The router is most valuable for tools without native equivalents — arxiv, playwright, memory, context7.
+
+## Planned
+
+- FAISS for >1000 tools (currently numpy cosine sim) — deferred; numpy is fine below ~1000 tools

mcp_sieve-0.1.0/config.example.yaml

@@ -0,0 +1,61 @@
+# MCP Sieve configuration
+# Copy this file to config.yaml and edit for your setup.
+# Real config.yaml is gitignored — it contains your local paths.
+
+# Downstream MCP servers that the router will aggregate.
+# Each entry spawns a stdio MCP server process.
+downstream:
+  - name: time
+    command: uvx
+    args: ["mcp-server-time"]
+
+  - name: fetch
+    command: uvx
+    args: ["mcp-server-fetch"]
+
+  - name: git
+    command: uvx
+    args: ["mcp-server-git", "--repository", "/path/to/your/repo"]
+
+  - name: arxiv
+    command: uvx
+    args: ["arxiv-mcp-server"]
+
+  # Windows: npx is a .cmd file — Python subprocess can't find it without a shell.
+  # Use "cmd /c npx" instead of just "npx".
+  - name: context7
+    command: cmd
+    args: ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
+
+  - name: filesystem
+    command: cmd
+    args: ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
+
+  - name: playwright
+    command: cmd
+    args: ["/c", "npx", "-y", "@playwright/mcp@latest"]
+
+  - name: sequential-thinking
+    command: cmd
+    args: ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
+
+  - name: memory
+    command: cmd
+    args: ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
+
+  # Remote MCP over HTTP (streamable) or SSE — no local process spawned.
+  # `transport` defaults to stdio; a bare `url` implies http.
+  - name: gitmcp
+    transport: http          # or: sse
+    url: "https://gitmcp.io/docs"
+
+# Env-var config (Docker/k8s, no file): MCP_SIEVE_DOWNSTREAM_1_NAME,
+# _COMMAND, _ARGS (JSON array or whitespace-split), _URL, _TRANSPORT.
+# N starts at 1 and stops at the first gap. Same-named env entry overrides yaml.
+# Also: MCP_SIEVE_OLLAMA_URL, MCP_SIEVE_EMBED_MODEL, MCP_SIEVE_TOP_N.
+
+# Embeddings settings (Ollama)
+embeddings:
+  ollama_url: "http://127.0.0.1:11434/api/embeddings"
+  model: "nomic-embed-text"
+  top_n: 10  # how many relevant tools to return per select call

mcp_sieve-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "mcp-sieve"
+version = "0.1.0"
+description = "MCP Sieve — semantic tool selection proxy for LLMs. Aggregates downstream MCP servers into 2 static tools (select + call) via Ollama embeddings."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "dimarch0x" }]
+keywords = ["mcp", "mcp-server", "semantic-routing", "llm", "ollama", "tool-selection"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "numpy>=1.26.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dimarch0x/mcp-sieve"
+Repository = "https://github.com/dimarch0x/mcp-sieve"
+Issues = "https://github.com/dimarch0x/mcp-sieve/issues"
+
+[project.scripts]
+mcp-sieve = "mcp_router.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_router"]

mcp_sieve-0.1.0/scripts/smoke_test.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Smoke test: send JSON-RPC requests to mcp-sieve via stdio.
+# Checks: initialize → tools/list → tools/call(mcp_router_select)
+
+set -e
+cd "$(dirname "$0")/.."
+
+# JSON-RPC initialize
+INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'
+# initialized notification
+INIT_DONE='{"jsonrpc":"2.0","method":"notifications/initialized"}'
+# tools/list
+LIST='{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+# tools/call mcp_router_select
+CALL='{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp_router_select","arguments":{"task":"get current time in UTC"}}}'
+
+# Pipe all requests, read responses
+printf '%s\n%s\n%s\n%s\n' "$INIT" "$INIT_DONE" "$LIST" "$CALL" | \
+  timeout 10 python -m mcp_router.server 2>/dev/null

mcp_sieve-0.1.0/src/mcp_router/__init__.py

@@ -0,0 +1 @@
+"""MCP Sieve package."""

mcp_sieve-0.1.0/src/mcp_router/server.py

@@ -0,0 +1,482 @@
+"""MCP Sieve — semantic tool selection proxy.
+
+Path 1 (notifications/tools/list_changed):
+  1. tools/list returns 1 tool: mcp_router_select
+  2. LLM calls mcp_router_select(task="...") → sieve finds top-N tools
+  3. Sieve updates current_tools + sends notifications/tools/list_changed
+  4. tools/list now returns the relevant tools
+  5. LLM calls a tool directly → sieve proxies to downstream
+
+Path 2 (mcp_router_call):
+  For clients with a frozen toolset (e.g. Hermes with prompt caching):
+  1. LLM calls mcp_router_select(task="...") → gets a list of suitable tools with their inputSchema.
+  2. LLM calls mcp_router_call(tool_name="...", arguments={...}) to execute the chosen tool.
+
+ponytail: one file, everything in it.
+"""
+import asyncio
+import contextlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import NamedTuple
+
+import httpx
+import numpy as np
+import yaml
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.server import NotificationOptions, Server
+from mcp.server.stdio import stdio_server
+from mcp.types import CallToolResult, EmbeddedResource, ImageContent, TextContent, Tool
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(name)s] %(message)s")
+log = logging.getLogger("mcp-sieve")
+
+# --- Config ------------------------------------------------------------------
+
+# ponytail: when launched via uvx --from <project>, the package lives in uv-cache,
+# __file__ points there. Look for config.yaml: (1) env MCP_ROUTER_CONFIG,
+# (2) next to CWD, (3) fallback to the old path relative to source.
+def _find_config() -> Path:
+    env = os.environ.get("MCP_ROUTER_CONFIG")
+    if env:
+        p = Path(env).expanduser()
+        if p.exists():
+            return p
+    cwd_cfg = Path.cwd() / "config.yaml"
+    if cwd_cfg.exists():
+        return cwd_cfg
+    src_cfg = Path(__file__).resolve().parent.parent.parent / "config.yaml"
+    return src_cfg
+
+CONFIG_PATH = _find_config()
+
+
+def _env_downstream() -> list[dict]:
+    """Read MCP_SIEVE_DOWNSTREAM_<N>_* env vars into downstream entries.
+
+    ponytail: for Docker/k8s where mounting a file is a pain. N starts at 1,
+    stops at the first gap. _ARGS is a JSON array (for quoting/backslashes) or
+    plain whitespace-split. _URL/_TRANSPORT enable HTTP/SSE downstream.
+    """
+    out: list[dict] = []
+    n = 1
+    while True:
+        name = os.environ.get(f"MCP_SIEVE_DOWNSTREAM_{n}_NAME")
+        if not name:
+            break
+        entry: dict = {"name": name}
+        for key, field in (("COMMAND", "command"), ("URL", "url"), ("TRANSPORT", "transport")):
+            val = os.environ.get(f"MCP_SIEVE_DOWNSTREAM_{n}_{key}")
+            if val:
+                entry[field] = val
+        raw_args = os.environ.get(f"MCP_SIEVE_DOWNSTREAM_{n}_ARGS")
+        if raw_args:
+            entry["args"] = json.loads(raw_args) if raw_args.lstrip().startswith("[") else raw_args.split()
+        out.append(entry)
+        n += 1
+    return out
+
+
+def _apply_env(cfg: dict) -> dict:
+    """Merge env-var overrides into a loaded config dict."""
+    downstream = cfg.get("downstream") or []
+    env_ds = _env_downstream()
+    if env_ds:
+        # name-keyed merge: env entry replaces a same-named yaml entry, else appends
+        by_name = {d["name"]: d for d in downstream}
+        for d in env_ds:
+            by_name[d["name"]] = d
+        cfg["downstream"] = list(by_name.values())
+
+    emb = cfg.setdefault("embeddings", {})
+    for key, field in (("OLLAMA_URL", "ollama_url"), ("EMBED_MODEL", "model")):
+        val = os.environ.get(f"MCP_SIEVE_{key}")
+        if val:
+            emb[field] = val
+    if os.environ.get("MCP_SIEVE_TOP_N"):
+        emb["top_n"] = int(os.environ["MCP_SIEVE_TOP_N"])
+    return cfg
+
+
+def load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        log.info("config.yaml not found (%s), relying on env vars", CONFIG_PATH)
+        return _apply_env({"downstream": [], "embeddings": {}})
+    log.info("loading config: %s", CONFIG_PATH)
+    cfg = yaml.safe_load(CONFIG_PATH.read_text(encoding="utf-8")) or {}
+    return _apply_env(cfg)
+
+
+CFG = load_config()
+EMBED_CFG = CFG.get("embeddings", {})
+OLLAMA_URL = EMBED_CFG.get("ollama_url", "http://127.0.0.1:11434/api/embeddings")
+EMBED_MODEL = EMBED_CFG.get("model", "nomic-embed-text")
+TOP_N = EMBED_CFG.get("top_n", 10)
+DOWNSTREAM = CFG.get("downstream", [])
+
+# --- State -------------------------------------------------------------------
+
+
+class RegisteredTool(NamedTuple):
+    downstream: str
+    orig_name: str
+    tool: Tool
+
+
+# ns_name → RegisteredTool
+tool_registry: dict[str, RegisteredTool] = {}
+# ns_name → embedding vector (np.ndarray)
+embeddings_cache: dict[str, np.ndarray] = {}
+# downstream_name → ClientSession
+downstream_sessions: dict[str, ClientSession] = {}
+# current tool list exposed via tools/list
+current_tools: list[Tool] = []
+
+# --- Embedding ---------------------------------------------------------------
+
+_embed_client: httpx.AsyncClient | None = None
+
+
+async def embed(text: str) -> np.ndarray:
+    """Get text embedding via Ollama. ponytail: in-memory cache, no DB."""
+    global _embed_client
+    if _embed_client is None:
+        _embed_client = httpx.AsyncClient(timeout=30)
+    r = await _embed_client.post(OLLAMA_URL, json={"model": EMBED_MODEL, "prompt": text})
+    r.raise_for_status()
+    return np.array(r.json()["embedding"], dtype=np.float32)
+
+
+def cosine_sim(a: np.ndarray, b: np.ndarray) -> float:
+    # ponytail: numpy — fine up to 1000 tools; beyond that use FAISS.
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-8))
+
+
+# --- Helpers -----------------------------------------------------------------
+
+
+def _text(text: str) -> list[TextContent]:
+    return [TextContent(type="text", text=text)]
+
+
+def _tool_dict(t: Tool) -> dict:
+    """Single serialization point for Tool → dict in select responses."""
+    return {"name": t.name, "description": t.description, "inputSchema": t.inputSchema}
+
+
+def _resolve(name: str) -> str | None:
+    """Resolve a tool name: exact → strip mcp_router_ prefix → unique suffix match.
+
+    ponytail: suffix match with uniqueness check — never silently picks the first.
+    'time' would match '..._get_time', but if >1 match → None (ambiguous).
+    """
+    if name in tool_registry:
+        return name
+    if name.startswith("mcp_router_"):
+        stripped = name[len("mcp_router_"):]
+        if stripped in tool_registry:
+            return stripped
+    matches = [n for n in tool_registry if n.endswith(f"_{name}")]
+    return matches[0] if len(matches) == 1 else None
+
+
+async def _invoke(entry: RegisteredTool, args: dict) -> list[TextContent]:
+    """Single point for calling a downstream session."""
+    session = downstream_sessions.get(entry.downstream)
+    if session is None:
+        return _text(f"downstream session {entry.downstream} not available")
+    try:
+        result: CallToolResult = await session.call_tool(entry.orig_name, args)
+        return result.content
+    except Exception as e:
+        log.exception("downstream call failed: %s/%s", entry.downstream, entry.orig_name)
+        return _text(json.dumps({"error": f"downstream call failed: {e}"}, ensure_ascii=False))
+
+
+# --- Downstream discovery ----------------------------------------------------
+
+async def _open_transport(ds: dict, exit_stack: contextlib.AsyncExitStack):
+    """Open the right transport for a downstream and return (read, write).
+
+    ponytail: transport defaults to stdio; a bare `url` implies http.
+    """
+    name = ds["name"]
+    transport = ds.get("transport") or ("http" if ds.get("url") else "stdio")
+    if transport == "stdio":
+        params = StdioServerParameters(command=ds["command"], args=ds.get("args", []), env=None)
+        log.info("connecting downstream %s (stdio): %s %s", name, params.command, params.args)
+        streams = await exit_stack.enter_async_context(stdio_client(params))
+    elif transport in ("http", "streamable-http"):
+        log.info("connecting downstream %s (http): %s", name, ds["url"])
+        streams = await exit_stack.enter_async_context(streamablehttp_client(ds["url"]))
+    elif transport == "sse":
+        log.info("connecting downstream %s (sse): %s", name, ds["url"])
+        streams = await exit_stack.enter_async_context(sse_client(ds["url"]))
+    else:
+        raise ValueError(f"unknown transport '{transport}' for downstream {name}")
+    return streams[0], streams[1]  # streamablehttp yields a 3rd session-id getter, ignore it
+
+
+async def _connect(ds: dict, exit_stack: contextlib.AsyncExitStack) -> ClientSession:
+    """Open transport + ClientSession + initialize. Shared by discovery and reconnect."""
+    read, write = await _open_transport(ds, exit_stack)
+    session = await exit_stack.enter_async_context(ClientSession(read, write))
+    await session.initialize()
+    return session
+
+
+async def _register_tools(name: str, session: ClientSession) -> None:
+    """Pull tools + build embeddings for one downstream. Idempotent across reconnects.
+
+    ponytail: a server's tool set is stable — register once, skip on reconnect.
+    """
+    if any(e.downstream == name for e in tool_registry.values()):
+        return  # already registered on a previous connect
+    try:
+        result = await session.list_tools()
+    except Exception as e:
+        log.error("failed to list tools from downstream %s: %s", name, e)
+        return
+    for tool in result.tools:
+        ns_name = f"{name}_{tool.name}"
+        ns_tool = Tool(name=ns_name, description=tool.description, inputSchema=tool.inputSchema)
+        tool_registry[ns_name] = RegisteredTool(name, tool.name, ns_tool)
+    try:
+        for ns_name, entry in list(tool_registry.items()):
+            if entry.downstream == name and ns_name not in embeddings_cache:
+                embeddings_cache[ns_name] = await embed(f"{entry.tool.name}: {entry.tool.description or ''}")
+        log.info("embeddings ready for %s (%d total)", name, len(embeddings_cache))
+    except Exception as e:
+        log.warning("embeddings failed for %s (%s), semantic search degraded", name, e)
+
+
+# ponytail: fixed backoff cap; make configurable if flapping servers appear.
+RECONNECT_BASE, RECONNECT_CAP, HEALTH_INTERVAL, STARTUP_TIMEOUT = 1.0, 30.0, 15.0, 60.0
+
+
+async def _supervise(ds: dict, ready: asyncio.Event) -> None:
+    """Keep one downstream connected; reconnect with exponential backoff on failure.
+
+    ponytail: each supervisor owns its exit_stack so connect/teardown run in the
+    same task — sidesteps anyio 'cancel scope in a different task'. Liveness via
+    periodic send_ping; a raised ping means the transport died.
+    """
+    name = ds["name"]
+    backoff = RECONNECT_BASE
+    while True:
+        try:
+            async with contextlib.AsyncExitStack() as stack:
+                session = await _connect(ds, stack)
+                downstream_sessions[name] = session
+                backoff = RECONNECT_BASE
+                log.info("downstream %s connected", name)
+                await _register_tools(name, session)
+                ready.set()
+                while True:
+                    await asyncio.sleep(HEALTH_INTERVAL)
+                    await session.send_ping()
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            downstream_sessions.pop(name, None)
+            ready.set()  # don't hold up startup on a server that won't connect
+            log.warning("downstream %s down (%s); reconnecting in %.0fs", name, e, backoff)
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, RECONNECT_CAP)
+
+
+# --- MCP Server --------------------------------------------------------------
+
+server: Server = Server("mcp-sieve")
+
+ROUTER_SELECT_TOOL = Tool(
+    name="mcp_router_select",
+    description=(
+        "REQUIRED first step before any task involving external tools. "
+        "Pass your current task description; returns the relevant tools "
+        "available for that task. Always call this first."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "task": {
+                "type": "string",
+                "description": "Natural language description of what you want to do.",
+            }
+        },
+        "required": ["task"],
+    },
+)
+
+ROUTER_CALL_TOOL = Tool(
+    name="mcp_router_call",
+    description=(
+        "Execute a downstream tool by name. Use after mcp_router_select "
+        "to find the right tool, then call this with the tool_name and "
+        "arguments from the select response."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "tool_name": {
+                "type": "string",
+                "description": "Tool name from mcp_router_select response (e.g. 'time_get_current_time').",
+            },
+            "arguments": {
+                "type": "object",
+                "description": "Arguments object matching the tool's inputSchema.",
+            },
+        },
+        "required": ["tool_name", "arguments"],
+    },
+)
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    """Return the current tool list."""
+    return current_tools
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict | None) -> list[TextContent] | list[ImageContent] | list[EmbeddedResource]:
+    """Tool call routing.
+
+    ponytail: Hermes may pass a prefixed name (mcp_router_time_get_current_time).
+    Strip mcp_router_ if the stripped name matches the registry or select.
+    """
+    args = arguments or {}
+
+    # ponytail: insurance — if the client passes a prefixed name, strip it
+    if name.startswith("mcp_router_"):
+        stripped = name[len("mcp_router_"):]
+        if stripped in ("mcp_router_select", "mcp_router_call") or stripped in tool_registry:
+            name = stripped
+
+    if name == "mcp_router_select":
+        return await _handle_select(args.get("task", ""))
+
+    if name == "mcp_router_call":
+        tool_name = args.get("tool_name", "")
+        tool_args = args.get("arguments", {})
+        if isinstance(tool_args, str):
+            try:
+                tool_args = json.loads(tool_args)
+            except Exception as e:
+                return _text(json.dumps({"error": f"failed to parse arguments JSON: {e}"}, ensure_ascii=False))
+
+        if not tool_name:
+            return _text(json.dumps({"error": "tool_name is required"}, ensure_ascii=False))
+
+        resolved = _resolve(tool_name)
+        if resolved is None:
+            return _text(json.dumps({"error": f"unknown tool: {tool_name}"}, ensure_ascii=False))
+        return await _invoke(tool_registry[resolved], tool_args)
+
+    # Direct downstream call by registry name
+    resolved = _resolve(name)
+    if resolved is not None:
+        return await _invoke(tool_registry[resolved], args)
+
+    return _text(json.dumps({"error": f"unknown tool: {name}"}, ensure_ascii=False))
+
+
+async def _handle_select(task: str) -> list[TextContent]:
+    """Core: semantic search for tools matching the task."""
+    if not task:
+        return _text('{"error": "task is required"}')
+
+    if not tool_registry:
+        return _text(json.dumps({
+            "info": "no downstream tools registered yet",
+            "available_tools": [t.name for t in current_tools],
+        }, ensure_ascii=False))
+
+    if not embeddings_cache:
+        # no embeddings — return all tools, don't break the flow
+        all_ns_tools = [entry.tool for entry in tool_registry.values()]
+        _set_current_tools(all_ns_tools)
+        return _text(json.dumps({
+            "warning": "embeddings unavailable; returning all tools",
+            "tools": [_tool_dict(t) for t in all_ns_tools],
+            "hint": "Use mcp_router_call(tool_name=<name>, arguments=<args>) to execute any of these tools.",
+        }, ensure_ascii=False))
+
+    q_vec = await embed(task)
+    scored: list[tuple[float, Tool]] = []
+    for ns_name, vec in embeddings_cache.items():
+        entry = tool_registry[ns_name]
+        scored.append((cosine_sim(q_vec, vec), entry.tool))
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    top = [t for _, t in scored[:TOP_N]]
+    _set_current_tools(top)
+
+    # notify the client (best-effort, only works inside a request context)
+    try:
+        ctx = server.request_context
+        await ctx.session.send_tool_list_changed()
+        log.info("sent tools/list_changed, now exposing %d tools", len(top))
+    except (LookupError, AttributeError) as e:
+        log.warning("cannot send list_changed outside active request: %s", e)
+    except Exception as e:
+        log.warning("could not send list_changed: %s", e)
+
+    payload = {
+        "selected_tools": [_tool_dict(t) for t in top],
+        "hint": "Use mcp_router_call(tool_name=<name>, arguments=<args>) to execute any of these tools.",
+    }
+    return _text(json.dumps(payload, ensure_ascii=False))
+
+
+def _set_current_tools(tools: list[Tool]) -> None:
+    """Update current_tools. Always keep mcp_router_select and mcp_router_call first."""
+    global current_tools
+    others = [t for t in tools if t.name not in ("mcp_router_select", "mcp_router_call")]
+    current_tools = [ROUTER_SELECT_TOOL, ROUTER_CALL_TOOL] + others
+
+
+# --- Entrypoint --------------------------------------------------------------
+
+async def main_async() -> None:
+    _set_current_tools([])
+
+    ready = [asyncio.Event() for _ in DOWNSTREAM]
+    supervisors = [
+        asyncio.create_task(_supervise(ds, ev), name=f"supervise-{ds['name']}")
+        for ds, ev in zip(DOWNSTREAM, ready)
+    ]
+    # Wait for the first connect attempt of each downstream so tools/list isn't
+    # empty on the first select — bounded so one slow server can't stall startup.
+    if ready:
+        with contextlib.suppress(asyncio.TimeoutError):
+            await asyncio.wait_for(
+                asyncio.gather(*(e.wait() for e in ready)), timeout=STARTUP_TIMEOUT
+            )
+
+    log.info("starting mcp-sieve on stdio, %d downstream connected, %d tools registered",
+             len(downstream_sessions), len(tool_registry))
+    try:
+        async with stdio_server() as (read, write):
+            await server.run(
+                read,
+                write,
+                server.create_initialization_options(NotificationOptions(tools_changed=True)),
+            )
+    finally:
+        for t in supervisors:
+            t.cancel()
+        await asyncio.gather(*supervisors, return_exceptions=True)
+
+
+def main() -> None:
+    asyncio.run(main_async())
+
+
+if __name__ == "__main__":
+    main()

mcp_sieve-0.1.0/test_transport_env_reconnect.py

@@ -0,0 +1,107 @@
+"""ponytail self-checks for env config (#2) and reconnect supervisor (#3).
+
+Run: python test_transport_env_reconnect.py
+No framework — plain asserts. Fails loudly if the logic breaks.
+"""
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, "src")
+import mcp_router.server as s
+
+
+def test_env_downstream():
+    env = {
+        "MCP_SIEVE_DOWNSTREAM_1_NAME": "time",
+        "MCP_SIEVE_DOWNSTREAM_1_COMMAND": "uvx",
+        "MCP_SIEVE_DOWNSTREAM_1_ARGS": "mcp-server-time --local",  # whitespace split
+        "MCP_SIEVE_DOWNSTREAM_2_NAME": "remote",
+        "MCP_SIEVE_DOWNSTREAM_2_URL": "https://example.com/mcp",
+        "MCP_SIEVE_DOWNSTREAM_2_ARGS": '["--flag", "with space"]',  # JSON keeps the quoted arg
+        # gap at 3 stops the scan; a stray 4 must be ignored
+        "MCP_SIEVE_DOWNSTREAM_4_NAME": "ignored",
+    }
+    old = dict(os.environ)
+    os.environ.update(env)
+    try:
+        ds = s._env_downstream()
+    finally:
+        os.environ.clear()
+        os.environ.update(old)
+
+    assert [d["name"] for d in ds] == ["time", "remote"], ds
+    assert ds[0]["args"] == ["mcp-server-time", "--local"], ds[0]
+    assert ds[1]["url"] == "https://example.com/mcp"
+    assert ds[1]["args"] == ["--flag", "with space"], ds[1]  # JSON preserved the space
+    print("ok: _env_downstream")
+
+
+def test_apply_env_merge():
+    cfg = {"downstream": [{"name": "time", "command": "old"}, {"name": "git", "command": "git"}]}
+    old = dict(os.environ)
+    os.environ.update({
+        "MCP_SIEVE_DOWNSTREAM_1_NAME": "time",       # same name → replaces
+        "MCP_SIEVE_DOWNSTREAM_1_COMMAND": "new",
+        "MCP_SIEVE_DOWNSTREAM_2_NAME": "arxiv",       # new name → appends
+        "MCP_SIEVE_DOWNSTREAM_2_COMMAND": "uvx",
+        "MCP_SIEVE_TOP_N": "5",
+    })
+    try:
+        out = s._apply_env(cfg)
+    finally:
+        os.environ.clear()
+        os.environ.update(old)
+
+    by_name = {d["name"]: d for d in out["downstream"]}
+    assert by_name["time"]["command"] == "new", by_name["time"]
+    assert by_name["git"]["command"] == "git"          # untouched yaml entry survives
+    assert by_name["arxiv"]["command"] == "uvx"        # env-only entry added
+    assert out["embeddings"]["top_n"] == 5
+    print("ok: _apply_env merge")
+
+
+def test_reconnect_supervisor():
+    """_supervise must survive a failed first connect and re-heal after the session dies."""
+    attempts = {"n": 0}
+
+    class FakeSession:
+        def __init__(self):
+            self.pinged = False
+
+        async def send_ping(self):
+            if self.pinged:            # dies on the 2nd ping
+                raise ConnectionError("transport gone")
+            self.pinged = True
+
+    async def fake_connect(ds, stack):
+        attempts["n"] += 1
+        if attempts["n"] == 1:
+            raise ConnectionError("first attempt fails")
+        return FakeSession()
+
+    async def noop_register(name, session):
+        return None
+
+    async def run():
+        s._connect = fake_connect
+        s._register_tools = noop_register
+        s.RECONNECT_BASE = s.RECONNECT_CAP = s.HEALTH_INTERVAL = 0.01
+        ready = asyncio.Event()
+        task = asyncio.create_task(s._supervise({"name": "x"}, ready))
+        await asyncio.sleep(0.3)
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        assert ready.is_set()                       # startup unblocked despite first failure
+        assert attempts["n"] >= 3, attempts         # failed once, connected+died, reconnected
+        assert "x" in s.downstream_sessions          # healed: a live session is registered
+
+    asyncio.run(run())
+    print("ok: _supervise reconnect")
+
+
+if __name__ == "__main__":
+    test_env_downstream()
+    test_apply_env_merge()
+    test_reconnect_supervisor()
+    print("all passed")