ai

View all files

Activity

Contributors

README

Mountaya AI

Everything public that helps an AI agent build with Mountaya, or contribute to a Mountaya repository:

  • Agent skills for the Mountaya products: Map Publishing, Embedded Studio and SDKs & Elements in TypeScript, the Data API, the MCP Server and the Tile API, plus authentication and webhooks.
  • The Mountaya MCP server configuration for Claude Code, Cursor, Codex and Gemini CLI.
  • Engineering plugins: the conventions Mountaya's public repositories share (TypeScript, Dart, Flutter, Kotlin, Swift) and the tooling policy that goes with them.
  • The workspace generator that keeps every Mountaya repository's agent setup identical.

Developer documentation lives at docs.mountaya.com.

This repository lives on Entire, at https://entire.com/et/mountaya/ai. Clone it with entire repo clone /et/mountaya/ai (the Entire CLI and an Entire login are needed); <ai-repo> below stands for the path of that checkout.

Agent skills

SkillProductUse it to
mountaya-authAllSet up publishable keys, secret keys and session tokens; send and retry writes safely; read rate limits and errors. Every other skill relies on it.
mountaya-webhooksAllReceive and verify signed webhook events, handle retries, duplicates and ordering, recover missed events, and find what emits each event.
mountaya-map-publishingMap PublishingPublish a read-only interactive map in an iframe.
mountaya-sdk-typescriptEmbedded Studio, SDKs & ElementsPick and use the @mountaya/* packages, from the embedded studio to the API client.
mountaya-data-apiData APICompute routes, suggestions, isochrones and matrices; geocode; read terrain; analyze geometry.
mountaya-mcpMCP ServerConnect an assistant to the Mountaya MCP Server and choose an authentication mode.
mountaya-tile-apiTile APIAdd Mountaya terrain, trail and weather layers to a MapLibre GL JS map.

Skills follow the Agent Skills standard.

Install

Any agent, through the skills CLI:

npx skills add https://docs.mountaya.com          # every skill
npx skills add https://docs.mountaya.com --skill mountaya-auth --skill mountaya-data-api

Skills installed this way do not update themselves. Run npx skills update -y to refresh them.

Claude Code, as a plugin that also registers the MCP server:

claude plugin marketplace add <ai-repo>
claude plugin install mountaya@mountaya

Cursor and Codex read .cursor-plugin/marketplace.json and .codex-plugin/marketplace.json at the root of this repository. Add <ai-repo> as a plugin source in either tool and install mountaya.

Gemini CLI, the MCP server only:

gemini extensions install <ai-repo>

Keys

Skills that call the API read two environment variables:

export MOUNTAYA_PUBLISHABLE_KEY="pk_..."
export MOUNTAYA_SECRET_KEY="sk_..."

Create both in the Mountaya app, under your organization's API keys tab. The secret key stays on a server: it does one thing, which is mint short-lived session tokens. mountaya-auth explains the rest.

MCP server

https://mcp.mountaya.com/ exposes the Data API as read-only tools. mcp/servers.json is the one place its configuration is written; every per-agent file in this repository, and the snippets inside the mountaya-mcp skill, are rendered from it.

Engineering plugins

For people working on a Mountaya repository. Each is a Claude Code plugin; its skills are plain SKILL.md files any agent can install with npx skills add <ai-repo> --skill <name>.

PluginShipsEnable for
mountaya-coregraph-first (Entire Graph before searching by hand) and retrieve-via-ctx skills, a session banner that reports Entire's state, a guard that keeps git and Entire's repository, trail and setup commands the person'severy repository
mountaya-typescripttypescript-conventions, google-typescript-best-practices, helix-ts-disciplinerepositories with TypeScript
mountaya-dartdart-conventions, a guard against dart compile artifactsrepositories with Dart
mountaya-flutterflutter-conventionsrepositories with Flutter
mountaya-kotlinkotlin-conventionsrepositories with Kotlin
mountaya-swiftswift-conventionsrepositories with Swift

A guard lives in the narrowest plugin where its rule always holds. A guard that fires where its rule does not hold teaches the reader to ignore guards.

Third-party skills are not redistributed here. Each repository vendors the ones it needs with npx skills, which records them in skills-lock.json.

One setup for every repository

A Mountaya repository does not hand-write its agent configuration. It keeps one file, .agents/manifest.json, naming the plugins and MCP servers it needs and its own permissions:

{
  "plugins": ["mountaya-typescript"],
  "mcp": ["playwright"],
  "permissions": { "deny": ["Bash(npm publish:*)"], "allow": ["Bash(npm run lint)"] },
  "siblings": ["schemas"]
}

Its gate lives beside its toolchain, in mise.toml: every repository has a ci task (the gate), a ci:quick task (formatting and linting) and the ones that ship a deploy task, so mise run ci is the gate in every repository whatever it is written in.

scripts/apply.mjs combines it with workspace/baseline.json (model, effort, where repositories live, the git and Entire deny lists, tooling) and mcp/servers.json, then renders:

FileWhat is managed
.claude/settings.jsonModel, effort, marketplaces, plugins, enabled MCP servers, permissions. Hooks and any other key are left as found.
.mcp.json, .cursor/mcp.json, .codex/config.tomlThe whole file, removed (with a folder it leaves empty) when it would declare no server
.claude/rules, .claude/skills/*Symlinks into .agents/rules and .agents/skills
AGENTS.mdThe block between the two mountaya-ai:tooling markers. The file itself is required: it is the entry point for every agent. The agent guide entire brain setup and entire graph setup write is taken out again: the tooling block says the same once
CLAUDE.mdCreated as @AGENTS.md when missing; a check fails when it does not start with that import
CONTRIBUTING.mdThe "Working with an AI agent" section between the two mountaya-ai:contributing markers, created with the file when missing
.gitignoreThe block every repository ignores: per-machine agent state, .DS_Store, .env files and stray .claude/ folders below the root
.editorconfig, .gitattributesThe shared head of each: editor defaults, and LF line endings. A repository's own sections and lines follow it
.entire/settings.jsonSession push (always, but never in a standalone repository), commit linking, telemetry and redaction
.agents/setupOne command that sets a clone up, from Entire to the toolchain: sh .agents/setup (--check to report only). It runs scripts/setup.mjs from the ai checkout beside the repository, installs mise where mise.toml pins a toolchain, and runs the manifest's setup on it
.githooks/From mise.toml's tasks: pre-commit (mise run ci:quick, after sh .agents/siblings sync pins and stages each sibling whose HEAD moved forward), pre-push (which on a push to main, from any local branch, warns about each of the manifest's pushWarnings, and stops a push only where sh .agents/siblings verify finds a pin CI could never fetch), and install, which wires them beside Entire's own git hooks, removes the hooks of that chain nothing runs any more, and which rendering runs when they are missing
.depot/workflows/ci.ymlThe gate on Depot CI, mise run ci, for every push to Entire: one job, or the parallel jobs the manifest's ciJobs splits it into. A repository that ships has its own ship.yml, which calls it first
.agents/siblingsPins the sibling commits CI builds against in siblings.lock (pin, and sync before every commit), stops a push carrying a pin CI could never fetch (verify), shows where each pin stands (status) and fetches them in CI; in a repository another one reads, publishes each pushed commit, in CI, as the git bundle those fetch (baseline siblings)
node ../ai/scripts/apply.mjs            # from a repository: render it
node ../ai/scripts/apply.mjs --check    # exit 1 on drift
make apply                              # from here: every sibling repository

The rendered files are committed, so a contributor who never checks out this repository still gets a working setup. Every Mountaya repository, public or internal, has the same shape: an internal contributor and an outside one open the same AGENTS.md, get the same settings and read the same onboarding section. To change something everywhere, edit the baseline and run make apply.

The full list of what every repository follows, and which of it is rendered or checked, is workspace/STANDARD.md.

Requirements

ToolHow it is installedWhat needs it
Node, Python, jqpinned in mise.tomlThe generator, the helpers and their fixture tests
npmcomes with NodeThe hook fixture tests
make, curlship with the systemmake check, and the helpers that fetch over HTTP

Setup

sh .agents/setup           # Entire, mise and the pinned tools, the git hooks, the dependencies
sh .agents/setup --check   # what is missing, changing nothing

Commands

CommandWhat it does
mise run lintThe skills, plugins and generated files, validated
mise run testThe hook, setup and helper fixture tests
mise run ci:quickWhat pre-commit runs: drift and validation
mise run ciThe gate: all of the above

Pre-commit runs mise run ci:quick. Every push to Entire runs mise run ci on Depot CI (.depot/workflows/ci.yml), and its result shows as checks on the commit.

Development

make sync     # rebuild providers/, the marketplaces and the shared blocks
mise run ci   # the gate (make check): drift + validation + hook, setup and helper tests

skills/, plugins/, mcp/, workspace/ and VERSION are sources. providers/, the three marketplace.json files, gemini-extension.json and every _mountaya_http.py are outputs: make check fails if one is edited by hand. See CONTRIBUTING.md.

License

MIT. See LICENSE.md. The google-typescript-best-practices skill is derived from the Google TypeScript Style Guide and stays under Apache-2.0, as its frontmatter declares.