Add @tiny-fish/mcp: local MCP proxy to agent.tinyfish.ai/mcp

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+---
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Type-check
+        run: npm run type-check
+      - name: Build
+        run: npm run build
+      - name: Unit tests
+        run: npm test
+
+  # Gated integration leg: runs the real-upstream suite only when the
+  # TINYFISH_API_KEY secret exists. GitHub does not allow `secrets.*` in a
+  # job-level `if:`, so the documented pattern is used instead — export the
+  # secret into the job env and branch on it inside a step. Fork PRs never
+  # receive secrets (the job-level `if:` also skips them outright), and the
+  # test suite itself skips with a notice when the key is empty, so this job
+  # is green-but-inert until the secret is configured.
+  integration:
+    runs-on: ubuntu-latest
+    needs: ci
+    if: github.event_name == 'push' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    env:
+      TINYFISH_API_KEY: ${{ secrets.TINYFISH_API_KEY }}
+    steps:
+      - name: Detect API key secret
+        id: key
+        run: |
+          if [ -n "$TINYFISH_API_KEY" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "TINYFISH_API_KEY secret not configured - skipping integration tests"
+          fi
+      - name: Checkout code
+        if: steps.key.outputs.present == 'true'
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        if: steps.key.outputs.present == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        if: steps.key.outputs.present == 'true'
+        run: npm ci
+      - name: Integration tests (real hosted upstream)
+        if: steps.key.outputs.present == 'true'
+        run: npm run test:integration

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+---
+name: Release
+# Publish @tiny-fish/mcp to npm when a v* tag is pushed (e.g. v0.1.0).
+# The tag itself is created by a human per docs/phases/release-runbook.md
+# (npm version + git push --follow-tags). Requires the NPM_TOKEN secret
+# (npm automation token for the @tiny-fish org) and id-token permission
+# for --provenance attestation.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Required for npm --provenance (Sigstore attestation via OIDC).
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - name: Install dependencies
+        run: npm ci
+      - name: Assert tag matches package.json version
+        # A mistyped tag (v0.2.0 on a 0.1.0 tree) must fail before publish.
+        run: |
+          pkg_version="$(node -p "require('./package.json').version")"
+          if [ "${GITHUB_REF_NAME}" != "v${pkg_version}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match package.json version ${pkg_version}" >&2
+            exit 1
+          fi
+      - name: Lint
+        run: npm run lint
+      - name: Type-check
+        run: npm run type-check
+      - name: Build
+        run: npm run build
+      - name: Unit tests
+        run: npm test
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,7 @@
+
+docs/
+.DS_Store
+/node_modules
+dist/
+.env
+coverage/

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2
+}

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of `@tiny-fish/mcp`: a local Streamable-HTTP MCP server at
+  `http://127.0.0.1:3711/mcp` that transparently reverse-proxies the hosted
+  TinyFish MCP server (`https://agent.tinyfish.ai/mcp`).
+- API-key auth: reads `TINYFISH_API_KEY` from the environment and sends it
+  upstream as `X-API-Key`, with `X-TF-Request-Origin` / `X-TF-Client-Name` /
+  `X-TF-Client-Version` attribution headers on every call.
+- Transparent pass-through of `initialize`, `ping`, `tools/list`,
+  `tools/call`, `resources/list`, and `resources/read`, including verbatim
+  forwarding of upstream JSON-RPC errors and byte-verbatim relay of the
+  `run_web_automation` SSE progress stream.
+- Session bridging: one upstream `Mcp-Session-Id` per local session; local
+  teardown aborts in-flight upstream requests (upstream has no DELETE).
+- Security guardrails: loopback-only bind (`127.0.0.1`, not configurable),
+  Origin-header allowlist (403 otherwise), and the API key never logged or
+  echoed.
+- Configuration via `PORT` (default `3711`) and `TINYFISH_UPSTREAM_URL`
+  (default hosted; `http:` allowed only for loopback hosts).
+- Locally shaped errors for upstream-leg failures: `-32001` (auth rejected,
+  HTTP 502), `-32000` (unreachable / stream failed, HTTP 502), with recovery
+  guidance and `runId` on mid-stream failures.
+- `tinyfish-mcp` bin, Node >= 22, ESM, published files limited to `dist/`,
+  `README.md`, `LICENSE`.
+
+[Unreleased]: https://github.com/tinyfish-io/tinyfish-mcp-server/commits/main

LICENSE

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