@portofcontext/pctx 0.1.1

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/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] - YYYY-MM-DD
+
+## [0.1.1] - 2025-11-10
+
+### Added
+
+- Initial release of pctx
+- Code mode interface for AI agent code execution
+- Upstream MCP server aggregation through a single interface
+- Secure authentication system (environment variables, keychain, arbitrary commands)
+- 2 Isolated Deno sandboxes: one for type checking and one for secure code execution
+- MCP server to agents functionality
+- Authentication and route management
+
+### Security
+
+- Code runs in isolated Deno sandbox with network host restrictions
+- No filesystem, environment, or system access beyond allowed hosts
+- MCP clients are authenticated, credentials hidden from LLMs an Deno env
+
+## [0.1.0] - 2025-11-10
+
+### Added
+
+- Initial public release
+
+[Unreleased]: https://github.com/portofcontext/pctx/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/portofcontext/pctx/compare/v0.1.1
+[0.1.0]: https://github.com/portofcontext/pctx/releases/tag/v0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <img src=".github/assets/logo.png" alt="PCTX Logo" style="height: 128px">
+  <h1>pctx</h1>
+
+[![Made by](https://img.shields.io/badge/MADE%20BY-Port%20of%20Context-1e40af.svg?style=for-the-badge&labelColor=0c4a6e)](https://portofcontext.com)
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/portofcontext/pctx/blob/main/LICENSE)
+[![Rust](https://img.shields.io/badge/rust-1.89%2B-blue.svg)](https://www.rust-lang.org)
+[![CI](https://github.com/portofcontext/pctx/workflows/CI/badge.svg)](https://github.com/portofcontext/pctx/actions)
+
+</div>
+
+<div align="center">
+
+The open source framework to connect AI agents to tools and services with [code mode](#what-is-code-mode)
+
+
+</div>
+
+## Pick installation method
+
+```bash
+# Homebrew
+brew install portofcontext/tap/pctx
+
+# Curl
+curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/portofcontext/pctx/main/install.sh | sh
+
+# npm and crates.io coming soon
+```
+
+## Quick Start
+
+```bash
+# Initialize config for upstream mcp connections
+pctx init
+
+# Connect to any MCP server
+pctx add my-local-server http://localhost:3000/mcp
+pctx add stripe https://mcp.stripe.com
+
+# Start the unified MCP server
+pctx start
+```
+
+For complete CLI documentation, see [CLI.md](docs/CLI.md).
+
+## What is pctx?
+
+`pctx` sits between AI agents and MCP servers. It aggregates multiple upstream MCP servers, handles authentication, and exposes tools through a unified Code Mode interface. Instead of agents managing connections to individual MCP servers, they connect once to pctx.
+
+## What is Code Mode?
+
+Code mode replaces sequential tool calling with code execution. Rather than an agent calling tools one at a time and passing results through its context window, it writes TypeScript code that executes in a sandbox. Read Anthropic's overview [here](https://www.anthropic.com/engineering/code-execution-with-mcp).
+
+**Traditional MCP flow**:
+1. Agent calls `getSheet(id)`
+2. Server returns 1000 rows → agent's context
+3. Agent calls `filterRows(criteria)`
+4. Server returns 50 rows → agent's context
+
+**With Code Mode**:
+```typescript
+const sheet = await gdrive.getSheet({ sheetId: 'abc' });
+const orders = sheet.filter(row => row.status === 'pending');
+console.log(`Found ${orders.length} orders`);
+```
+
+**Result:** 98.7% reduction in tokens (150k → 2k) for this multi-step operation.
+
+## Features
+
+- **Code Mode interface**: Tools exposed as TypeScript functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
+- **Upstream MCP server aggregation**: Connect to multiple MCP servers through a single interface. See [Upstream MCP Servers Guide](docs/upstream-mcp-servers.md).
+- **Secure authentication**: OAuth, environment variables, system keychain, and external commands. See [Authentication Guide](docs/mcp-auth.md).
+
+## Architecture
+
+```
+    Runs locally • in docker • any cloud
+
+  ┌─────────────────────────────────┐
+  │      AI Agents (Bring any LLM)  │
+  └──────────────-──────────────────┘
+                │ MCP
+                │ • list_functions
+                │ • get_function_details
+                │ • execute
+  ┌─────────────▼───────────────────┐
+  │            pctx                 │
+  │                                 │
+  │  ┌─────────────────────────┐    │
+  │  │  TypeScript Compiler    │    │
+  │  │  Sandbox (Deno)         │    │
+  │  │                         │    │
+  │  │  • Type checking        │    │
+  │  │  • Rich error feedback  │    │
+  │  │  • No network access    │    │
+  │  └──────────┬──────────────┘    │
+  │             │ Compiled JS       │
+  │  ┌──────────▼──────────────┐    │
+  │  │  Execution Sandbox      │    │
+  │  │  (Deno Runtime)         │    │
+  │  │                         │    │
+  │  │  • Authenticated MCP    │    │
+  │  │    client connections   │    │
+  │  │  • Restricted network   │    │
+  │  │  • Tool call execution  │    │
+  │  └──┬──────┬──────┬────────┘    │
+  └─────┼──────┼──────┼─────────────┘
+        │      │      │
+        ↓      ↓      ↓
+    ┌──────┬──────┬──────┬──────┐
+    │Local │Slack │GitHub│Custom│
+    └──────┴──────┴──────┴──────┘
+```
+
+
+## Security
+
+- LLM generated code runs in an isolated [Deno](https://deno.com) sandbox that can only access the network hosts specified in the configuration file.
+- No filesystem, environment, network (beyond allowed hosts), or system access.
+- MCP clients are authenticated. LLMs cannot access auth.
+
+
+## Learn More
+
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+- [Code execution with MCP by Anthropic](https://www.anthropic.com/engineering/code-execution-with-mcp)
+- [Code Mode explanation by Cloudflare](https://blog.cloudflare.com/code-mode/)

package/binary-install.js

@@ -0,0 +1,212 @@
+const { createWriteStream, existsSync, mkdirSync, mkdtemp } = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const axios = require("axios");
+const rimraf = require("rimraf");
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(fetchOptions, suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    if (existsSync(this.installDirectory)) {
+      rimraf.sync(this.installDirectory);
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return axios({ ...fetchOptions, url: this.url, responseType: "stream" })
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            let tempFile = join(directory, this.filename);
+            const sink = res.data.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName, fetchOptions) {
+    const promise = !this.exists()
+      ? this.install(fetchOptions, true)
+      : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+        process.exit(1);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,126 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const cTable = require("console.table");
+const libc = require("detect-libc");
+const { configureProxy } = require("axios-proxy-builder");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrl,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMInorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMInorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(platform, name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const package = getPackage();
+  const proxy = configureProxy(package.url);
+
+  return package.install(proxy, suppressLogs);
+};
+
+const run = (binaryName) => {
+  const package = getPackage();
+  const proxy = configureProxy(package.url);
+
+  package.run(binaryName, proxy);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);