opencode-palantir

OpenCode plugin that provides:

• Palantir public documentation tools backed by a local Parquet database
• Foundry MCP bootstrapping helpers (commands, agents, and optional auto-bootstrap)

NPM package: https://www.npmjs.com/package/@openontology/opencode-palantir

Supported OS

• Supported: macOS, Linux
• Windows: not supported (WSL2 might work, but we don’t debug Windows-specific issues)

Install (OpenCode)

Add the plugin in your OpenCode config (opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@openontology/opencode-palantir@^0.1.4"]
}

Restart OpenCode.

After enabling the plugin, OpenCode will automatically register:

• Tools: get_doc_page, list_all_docs
• Commands: /refresh-docs, /refresh-docs-rescrape, /setup-palantir-mcp, /rescan-palantir-mcp-tools
• Agents: foundry-librarian, foundry

Versions: how to get the latest

Prefer pinned or semver range installs (like @^0.1.4), and update intentionally.

Avoid using @latest in config:

• it can make startup slower (npm resolution/install on startup)
• it makes behavior less deterministic
• depending on caching, you may not get the upgrade behavior you expect

To find the newest version and changelog:

• NPM versions: https://www.npmjs.com/package/@openontology/opencode-palantir
• GitHub releases: https://github.com/anand-testcompare/opencode-palantir/releases
• Repo changelog: CHANGELOG.md

(Optional) Install per-project

In your project repo, add the plugin as a dependency inside .opencode/ (keeps plugin deps separate
from your app deps):

mkdir -p .opencode

cat > .opencode/package.json <<'EOF'
{
  "dependencies": {
    "@openontology/opencode-palantir": "^0.1.4"
  }
}
EOF

(cd .opencode && bun install)

Then create a tiny wrapper file in .opencode/plugins/:

mkdir -p .opencode/plugins

cat > .opencode/plugins/opencode-palantir.js <<'EOF'
import plugin from '@openontology/opencode-palantir';

export default plugin;
EOF

OpenCode automatically loads .js/.ts files from .opencode/plugins/ at startup.

Environment variables (Foundry MCP)

This plugin never writes Foundry environment values to disk. In opencode.jsonc, FOUNDRY_URL
and FOUNDRY_TOKEN are referenced as {env:FOUNDRY_URL} and {env:FOUNDRY_TOKEN}.

Variables

• FOUNDRY_URL
  • Foundry base URL (used for auto-bootstrap, /setup-palantir-mcp, and /rescan-palantir-mcp-tools)
  • Example: https://YOUR-STACK.palantirfoundry.com
• FOUNDRY_TOKEN
  • Foundry token used by palantir-mcp for tool discovery
  • Must be exported (not just set in a shell)

Recommended setup (zsh, macOS/Linux)

Use your existing shell secrets file. For example, if you already source ~/.shell_secrets from
~/.zshrc, add:

export FOUNDRY_URL='https://YOUR-STACK.palantirfoundry.com'
export FOUNDRY_TOKEN='YOUR_TOKEN'

Lock it down:

chmod 600 ~/.shell_secrets

Ensure ~/.zshrc sources it:

if [ -f "$HOME/.shell_secrets" ]; then
  source "$HOME/.shell_secrets"
fi

If you still see “token not exported” errors, verify echo $FOUNDRY_TOKEN prints a value and that
it’s exported in the environment where OpenCode is launched.

Docs tools (Palantir public docs)

The docs DB is a local file:

• data/docs.parquet (in your repo root)

First-run behavior

On startup and tool usage, the plugin automatically ensures data/docs.parquet exists by using a
prebuilt snapshot (download/copy). In most repos, docs tools should work without any manual setup.

Refresh commands

• /refresh-docs (recommended)
  • Force refresh from a prebuilt snapshot (no live rescrape)
• /refresh-docs-rescrape (unsafe/experimental fallback)
  • Live-rescrapes palantir.com docs and rebuilds data/docs.parquet
  • Use only when snapshot download/copy is blocked

Tools

• get_doc_page
  • Retrieve a doc page by URL, or fuzzy match by query
• list_all_docs
  • List docs with pagination and optional query/scope filtering

Foundry MCP helpers

This plugin registers Foundry commands and agents automatically at startup (config-driven).

Auto-bootstrap (no command required)

If you set both FOUNDRY_TOKEN and FOUNDRY_URL, the plugin will automatically and idempotently
patch repo-root opencode.jsonc to initialize:

• mcp.palantir-mcp local server config
• global tool deny: tools.palantir-mcp_* = false
• per-agent allow/deny toggles under foundry-librarian and foundry

Guided setup and maintenance

• /setup-palantir-mcp
  • Creates/patches repo-root opencode.jsonc
  • Adds mcp.palantir-mcp (if missing) as a local npx palantir-mcp --foundry-api-url ... server backed by {env:FOUNDRY_URL}
  • Enforces global deny: tools.palantir-mcp_* = false
  • Creates foundry-librarian and foundry agents
  • Discovers palantir-mcp tools and writes explicit true/false toggles under each agent
• /rescan-palantir-mcp-tools
  • Re-discovers the palantir-mcp tool list and adds missing explicit toggles
  • Never overwrites existing palantir-mcp_* toggles

About palantir-mcp versions (important)

The generated MCP server uses npx -y palantir-mcp ... by default.

Notes:

• First run can be slow (npx may need to download/install).
• @latest / unpinned installs are less deterministic.

Recommendation: once you’re set up, pin the version in opencode.jsonc:

{
  "mcp": {
    "palantir-mcp": {
      "type": "local",
      "command": [
        "node",
        "-e",
        "const { spawn } = require('node:child_process'); const raw = (process.env.FOUNDRY_URL || '').trim(); const withScheme = /^https?:\\/\\//i.test(raw) ? raw : `https://${raw}`; const url = new URL(withScheme); const foundryUrl = `${url.protocol}//${url.host}`; const command = process.platform === 'win32' ? 'npx.cmd' : 'npx'; const child = spawn(command, ['-y', 'palantir-mcp@<version>', '--foundry-api-url', foundryUrl], { stdio: 'inherit' }); child.on('exit', (code) => process.exit(code ?? 1));"
      ],
      "environment": {
        "FOUNDRY_URL": "{env:FOUNDRY_URL}",
        "FOUNDRY_TOKEN": "{env:FOUNDRY_TOKEN}"
      }
    }
  }
}

Development (this repo)

Setup

mise run setup

Common tasks

• Build: mise run build
• Test: mise run test
• Lint: mise run lint
• Typecheck: mise run typecheck
• Format: mise run format

Smoke test the built artifact

mise run smoke

Fetch docs parquet (local dev)

Fetch all Palantir docs into data/docs.parquet (~2 minutes, ~17MB file):

bun run src/docs/fetch-cli.ts

Parquet schema (local dev)

The Parquet file contains a single row group with the following columns:

Example (Bun):

import { parquetReadObjects } from 'hyparquet';

const file = await Bun.file('data/docs.parquet').arrayBuffer();

// List all pages (url + title only)
const pages = await parquetReadObjects({ file, columns: ['url', 'title'] });
console.log(`${pages.length} pages`);

Release notes

For maintainers, see RELEASING.md.

Author

Anand Pant [email protected]