SageMath MCP

SageMath em sandbox para agentes: 40 ferramentas para matemática exata e simbólica com sessão persistente

Documentação

Servidor SageMath MCP

Um servidor Model Context Protocol que fornece a um LLM um subconjunto matemático isolado do SageMath — cálculo simbólico, teoria dos números, álgebra linear, EDOs, plotagem, combinatória, grafos, grupos, curvas elípticas e muito mais. Cada sessão MCP recebe um processo de trabalho Sage dedicado, portanto variáveis, funções e suposições persistem entre chamadas de ferramentas. Ele inclui 40 ferramentas MCP, uma das quais — verify_claim — verifica novamente um resultado declarado por meio de uma escada de prova e responde proved / refuted / supported / undecided com suas evidências.

O código do chamador é negado por padrão: toda a amplitude da matemática do Sage é alcançável, mas importações, interfaces CAS externas e primitivas de arquivo / exibição / persistência não são. A política aceita 98,9% dos 438.124 exemplos de doctest documentados do próprio SageMath (4.259 recusas no escopo, cada uma atribuída a uma regra nomeada; 99,0% de 433.289 no runtime passagemath) enquanto recusa o restante — medido em cada execução de CI (consulte Segurança).

Manual completo: USAGE.md — parâmetros e exemplos de cada ferramenta, como o código é interpretado e o modelo de segurança em profundidade.

Instalação e execução

Recomendado — a imagem de contêiner (SageMath já incluído):

docker run --rm \
  --read-only --tmpfs /tmp:rw,size=512m --tmpfs /home/sage/.sage:rw,size=256m \
  --cap-drop ALL --security-opt no-new-privileges --pids-limit 256 --memory 4g \
  -p 127.0.0.1:8314:8314 \
  ghcr.io/xbp-europe/sagemath-mcp:latest

Essas flags são o endurecimento que o servidor espera; a porta é publicada no loopback deliberadamente — o servidor executa código e não autentica ninguém. docker compose up --build aplica o mesmo endurecimento a partir de um arquivo revisado. As imagens lançadas são assinadas com Cosign e carregam proveniência SLSA e um SBOM SPDX como atestados de registro; os arquivos PyPI carregam atestados PEP 740. DISTRIBUTION.md mostra como verificar cada um.

Do PyPI (traga seu próprio runtime Sage):

pip install sagemath-mcp
sagemath-mcp                                             # stdio (default)
sagemath-mcp --transport streamable-http --port 8314    # HTTP on 127.0.0.1

Isso requer um SageMath funcional no host — seja sage no seu PATH (ou no mesmo ambiente que o servidor) ou a imagem Docker sagemath/sagemath.

Do conda-forge (Linux e macOS, ao lado do Sage do conda-forge):

conda install -c conda-forge "sagemath-mcp>=0.9.4" sage
sagemath-mcp

O piso de versão importa: versões anteriores não conseguem iniciar um worker no sage do conda-forge, e sem ele o resolvedor pode escolher um. Esse sage é 10.9, uma versão atrás do 10.10 do qual os artefatos de segurança são gerados, portanto nomes adicionados no 10.10 não estão disponíveis e nada fora da lista de permissões é admitido.

Um runtime Sage sem a imagem de 3 GB (passagemath, opcional):

pip install "sagemath-mcp[passagemath]"    # ~1 GB, no Docker, no local Sage build
sagemath-mcp

Um fork modularizado e instalável via pip do SageMath. from sage.all import * e o worker rodam sem modificações; o servidor detecta o runtime na importação e carrega os artefatos de segurança correspondentes, portanto a política de negação por padrão é equivalente em ambos. Ele é fixado exatamente (passagemath-standard==10.8.12) e exercitado por sua própria faixa de CI — a suíte completa mais a varredura do corpus de doctests contra o pin — portanto, um aumento de pin é verificado de ponta a ponta antes de ser lançado (docs/passagemath_evaluation.md). Ele é o runtime opcional; a imagem monolítica permanece primária, e para uso não confiável ou multiusuário, execute o contêiner independentemente do runtime — uma instalação pip tem os privilégios do seu usuário, o contêiner adiciona isolamento em nível de SO.

Em arm64 (silício da Apple, Graviton): a imagem passagemath. A imagem monolítica acima é publicada apenas para linux/amd64, portanto, em arm64 ela roda sob emulação. O mesmo servidor no runtime passagemath é distribuído como uma imagem nativa linux/amd64 + linux/arm64, com as mesmas flags de endurecimento, UID e política de segurança:

docker run --rm \
  --read-only --tmpfs /tmp:rw,size=512m --tmpfs /home/sage/.sage:rw,size=256m \
  --cap-drop ALL --security-opt no-new-privileges --pids-limit 256 --memory 4g \
  -p 127.0.0.1:8314:8314 \
  ghcr.io/xbp-europe/sagemath-mcp:latest-passagemath

Cada tag de lançamento tem um gêmeo -passagemath (vX.Y.Z-passagemath), cada arquitetura é testada nativamente antes de ser publicada, e o índice é assinado e atestado como a imagem primária. Ela é a imagem opcional em amd64, onde a monolítica permanece primária.

Um clique em um host MCP de desktop (Claude Desktop e similares): baixe sagemath-mcp-<version>.mcpb do último lançamento e abra-o. O pacote tem alguns kilobytes; seu host instala o servidor e um runtime Sage com uv no primeiro lançamento, o que é aproximadamente um download de 1 GB uma vez. macOS e Linux — Windows nativo é excluído porque o suporte ao Windows do passagemath é parcial. Um pacote é uma instalação local com seus próprios privilégios; para uso não confiável ou multiusuário, execute o contêiner.

Instalação a partir do código-fonte, Docker Compose e o gráfico Helm do Kubernetes estão em USAGE.md.

Conecte um cliente MCP

Um comando ou um clique cada. Cada rota abaixo instala um runtime Sage junto ao servidor, portanto não há mais nada para configurar.

Claude Desktop — baixe sagemath-mcp-<version>.mcpb do último lançamento e abra-o. Um clique, sem arquivo de configuração.

Claude Code — como um plugin do marketplace deste repositório, dentro de uma sessão:

/plugin install sagemath-mcp --marketplace XBP-Europe/sagemath-mcp

ou como um servidor MCP simples:

claude mcp add sagemath -- uvx --from "sagemath-mcp[passagemath]" sagemath-mcp

Gemini CLI — o repositório é em si uma extensão:

gemini extensions install https://github.com/XBP-Europe/sagemath-mcp

Codex CLI

codex mcp add sagemath -- uvx --from "sagemath-mcp[passagemath]" sagemath-mcp

Então peça alguma matemática — os exemplos abaixo são um bom começo.

Três coisas que vale a pena saber. Elas precisam de uv no seu PATH, e o primeiro lançamento baixa cerca de 1 GB de wheels do Sage, armazenados em cache depois. Já tem sage? Remova [passagemath] da especificação e ele usará o seu. Instalou do conda-forge? Registre o executável do próprio ambiente, por exemplo claude mcp add sagemath -- ~/miniforge3/envs/sage/bin/sagemath-mcp; ele encontra o sage ao lado dele sem que o ambiente seja ativado. E uma instalação de qualquer um deles roda com seus próprios privilégios; para uso não confiável ou compartilhado, execute o contêiner e aponte o cliente para ele.

Fixar um lançamento, transporte HTTP e a referência completa do cliente estão em USAGE.md.

Experimente

Prompts que um cliente pode executar assim que o servidor estiver conectado:

Oscilador harmônico amortecido — "Resolva x'' + 2·x' + 5·x = 0 com x(0)=1, x'(0)=0, então verifique se a solução satisfaz a EDO."
Relatividade geral — "No semiplano superior hiperbólico com a métrica (dx² + dy²)/y², calcule o escalar de Ricci e confirme que é uma curvatura negativa constante."
Sistema acoplado de dois tanques — "Resolva o sistema linear de EDOs para dois tanques de mistura, então tome o limite de longo prazo de cada concentração."

Cada um constrói um objeto uma vez e o explora em várias chamadas — o caso para evaluate_sage e sua sessão persistente.

As 40 ferramentas

As ferramentas matemáticas usam o SageMath como backend; parâmetros completos e exemplos estão em USAGE.md.

Categoria	Ferramentas
Execução principal	`evaluate_sage`, `evaluate_sage_streaming`
Verificação	`verify_claim`
Cálculo	`differentiate_expression`, `integrate_expression`, `limit_expression`, `series_expansion`
Álgebra	`solve_equation`, `simplify_expression`, `expand_expression`, `factor_expression`, `calculate_expression`, `symbolic_sum`
Álgebra linear	`matrix_multiply`, `matrix_operation`
Equações diferenciais	`solve_ode`
Teoria dos números	`number_theory_operation`
Combinatória	`combinatorics_operation`
Teoria de grafos / grupos	`graph_operation`, `group_operation`
Curvas elípticas / codificação	`elliptic_curve_operation`, `coding_theory_operation`
Polinômios / booleanos / geometria	`polynomial_ring_operation`, `boolean_algebra_operation`, `geometry_operation`
Estatística / probabilidade	`statistics_summary`, `distribution_operation`
Visualização	`plot_expression`, `plot3d_expression`, `plot_multi_expression`
Métodos numéricos / cálculo vetorial	`find_root`, `vector_calculus_operation`
Controle de sessão	`reset_sage_session`, `interrupt_sage_session`, `cancel_sage_session`
Espaços de trabalho nomeados	`start_sage_session`, `list_sage_sessions`, `stop_sage_session`
Diagnóstico	`check_sage_health`, `lookup_sage_doc`

Além de endpoints HTTP /health e /ready e 3 recursos MCP (instantâneos de sessão, métricas de monitoramento, links de documentação). Prefira interrupt_sage_session a cancel_sage_session — ele interrompe uma computação enquanto mantém as variáveis da sessão.

Como funciona

┌─────────────────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Gemini CLI, Codex CLI, ...)    │
└───────────────────────────┬─────────────────────────────────┘
                            │  MCP protocol (stdio or HTTP)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  app.py + tools/ --- FastMCP 4.x                            │
│  ┌─────────────┐  ┌──────────────┐                          │
│  │ 40 MCP Tools│  │ 3 Resources  │   manager.py routes each │
│  └─────────────┘  └──────────────┘   client to its worker   │
└───────────────────────────┬─────────────────────────────────┘
                            ▼   one subprocess per session
┌─────────────────────────────────────────────────────────────┐
│  _sage_worker.py --- allowlist.py + security.py             │
│  AST validation, then exec() in a persistent namespace      │
│  (vars, functions and classes survive across calls)         │
└─────────────────────────────────────────────────────────────┘

Fluxo de solicitação: cliente MCP → uma ferramenta em tools/ → SageSessionManager.get() → SageSession.evaluate() → solicitação JSON para o subprocesso _sage_worker.py → validação AST → exec() no namespace persistente → resposta JSON.

Isolamento de processo — cada sessão executa o Sage em seu próprio subprocesso; uma falha ou tempo limite em uma não pode afetar outra.
Sessões com estado — variáveis, funções e suposições persistem entre chamadas, permitindo fluxos de trabalho em várias etapas.
Negação por padrão — um nome é recusado a menos que a lista de permissões gerada o ofereça ou o próprio código do chamador o tenha vinculado. Um auxiliar que um SageMath futuro adicionar é recusado até que alguém o revise, em vez de ficar acessível no dia em que for lançado.

Segurança

O validador AST é defesa em profundidade contra acidentes e uso indevido casual — ele não é uma fronteira contra código adversário determinado. O contêiner é a fronteira de segurança. O servidor não tem autenticação, portanto todo padrão é loopback: --host padrão é 127.0.0.1, o transporte padrão é stdio, e Compose / Helm mantêm o endpoint fora da rede. Coloque algo que autentique na frente dele antes de expô-lo.

O que a política impõe: uma lista de permissões (o código do chamador pode ler apenas um nome que o servidor oferece ou que o próprio chamador vinculou); sem importações por padrão; eval / exec / compile e avaliação de string em runtime bloqueadas; acesso a dunder bloqueado; as interfaces CAS externas e toda primitiva de arquivo / rede / persistência removidas do namespace, por proveniência em vez de por nome; e a árvore de pacotes sage fechada ao código do chamador, portanto um auxiliar é alcançado por seu próprio nome ou de forma alguma. O contêiner adiciona uma raiz somente leitura, capacidades removidas, no-new-privileges, o perfil seccomp padrão e tetos de memória. O Compose adiciona um teto de fork (PID); o Kubernetes não tem equivalente por pod na especificação do pod, portanto, no gráfico, isso é o podPidsLimit do nó, em vez de algo que o gráfico possa definir.

Modelo de ameaça completo e as tabelas completas de bloqueados / permitidos: SECURITY.md e USAGE.md § Modelo de segurança.

Documentação e mais

USAGE.md — o manual completo: cada ferramenta, como o código é interpretado, implantação e o modelo de segurança.
docs/mcp_quickstart.md — um passo a passo da primeira sessão.
CHANGELOG.md · ROADMAP.md · CONTRIBUTING.md · SECURITY.md · SUPPORT.md — o que "suportado" significa, cadência de lançamentos, onde perguntar. PRIVACY.md — o que o servidor mantém (nada sai da máquina em que ele roda).

Requisitos

Python 3.12+ e um runtime SageMath (a imagem do contêiner inclui SageMath 10.10; caso contrário, sage em PATH, ou o extra [passagemath]). Construído sobre FastMCP 4.x.

Contribuindo

Issues e pull requests são bem-vindos — veja CONTRIBUTING.md. Execute make lint, make typecheck e make test antes de enviar (git config core.hooksPath .githooks configura a verificação pré-push). Roadmap e trabalho em aberto: ROADMAP.md. Perguntas vão para GitHub Discussions; SUPPORT.md diz o que esperar.

Citação

Se este servidor fizer parte de um trabalho publicado, cite-o via CITATION.cff — o GitHub o renderiza como Cite this repository na barra lateral, com APA e BibTeX. Cite também o próprio SageMath; ele faz a matemática.

Licença

MIT — veja LICENSE. O SageMath em si é GPL-2.0-or-later e é usado como um runtime separado; nenhum código-fonte do SageMath é redistribuído neste repositório.