my-pi

my-pi

Runtime MCP local-first para agentes de codificação — acesso seguro ao workspace sem um shell irrestrito
_{Sistema de arquivos limitado · gravações com pré-condição de conteúdo · busca AST Tree-Sitter · navegação LSP · ferramentas Git}

O que é o my-pi?

my-pi é um runtime determinístico local de capacidades de codificação exposto por meio do oficial Model Context Protocol (MCP). Ele dá a agentes de codificação compatíveis com MCP acesso controlado a um workspace real por meio de autoridade explícita de workspace, leituras limitadas, gravações protegidas, busca estrutural, inteligência de language server e operações Git.

Ele é voltado para desenvolvedores que desejam que ferramentas de codificação agênticas entendam e modifiquem código sem entregar ao agente um shell de propósito geral ou conceder silenciosamente o diretório de trabalho atual.

Por que usar?

• Local-first: o código-fonte e o estado detalhado do workspace permanecem no host.
• Somente leitura por padrão: gravações e inicialização de processos de language server exigem elevação explícita via trusted.
• Mutação mais segura: gravações podem exigir pré-condições de conteúdo SHA-256 em vez de semântica de sobrescrita cega.
• Busca ciente de código: busca estrutural Tree-Sitter em TypeScript, JavaScript, Python, Rust e Go.
• Navegação semântica: símbolos LSP, definições, referências, hover e diagnósticos para language servers de host suportados.
• Contexto ciente de Git: operações limitadas de status e diff com filtragem de segredos e transbordamento de diffs grandes.
• Sem dependência secundária de LLM pago: o runtime principal executa localmente e não seleciona modelos nem gera agentes.

Canal de lançamento: Alpha. O selo npm acima é a autoridade para a versão do pacote atualmente publicada. Este repositório pode conter um candidato a lançamento mais recente antes da publicação ser concluída. Adequado para avaliação e desenvolvimento local controlado; revise o modelo de segurança antes de habilitar o perfil confiável.

Instale em menos de um minuto

Requer Node.js >=22.6.0.

npm install -g @koonwang03/my-pi
my-pi-mcp --workspace /path/to/your/project

O servidor inicia em modo somente leitura. Para um workspace que você confia explicitamente:

my-pi-mcp --workspace /path/to/your/project --security-profile trusted

Ou inspecione uma configuração de host sem instalação global:

npx --yes --package @koonwang03/my-pi my-pi-mcp host-config cursor-local

Gere trechos de configuração específicos do host:

my-pi-mcp host-config claude-code-local
my-pi-mcp host-config cursor-local
my-pi-mcp host-config opencode-current-local

Iniciar sem --workspace ou MY_PI_WORKSPACE_ROOT falha de forma segura. Use --allow-cwd somente quando conceder o diretório atual for intencional.

Superfície MCP de 13 ferramentas

Área	Ferramentas	Propósito
Sistema de arquivos	fs_read, fs_write, fs_patch, fs_stat	Leituras limitadas, gravações/patches protegidos, metadados
Busca e workspace	search, workspace_info	Exploração de repositório e estado autoritativo do workspace
AST e LSP	ast_search, lsp_status, lsp_symbols, lsp_navigate, lsp_diagnostics	Inteligência estrutural e semântica de código
Git	vcs_status, vcs_diff	Status do repositório e diffs limitados/filtrados

Garantias principais

Capacidade	Comportamento
Mutação com pré-condição de conteúdo	Atualizações de arquivo verificam impressões digitais SHA-256 brutas e rejeitam sobrescritas protegidas obsoletas
Política de pré-leitura de caminhos sensíveis	Caminhos sensíveis como .env*, .aws/, .ssh/ e *.key são negados antes que o conteúdo seja alocado ao contexto do modelo
Perfis de segurança explícitos	O padrão é somente leitura; mutação e inicialização de processos LSP exigem elevação explícita
Fidelidade de codificação/modo	A substituição de arquivos preserva codificação relevante, finais de linha, BOM e comportamento de modo executável POSIX
Cancelamento	Trabalho de subprocesso Git/busca/LSP de longa duração suporta cancelamento e limpeza

Arquitetura

MCP-capable coding host
        │
        │ stdio
        ▼
┌─────────────────────┐
│   my-pi MCP edge    │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ capability contracts│
└──────────┬──────────┘
           ▼
┌─────────────────────────────────────────────────────────┐
│ workspace │ policy │ filesystem │ search │ AST │ LSP │ Git │
└─────────────────────────────────────────────────────────┘
           │
           └── local host workspace

A alegação pública estável é a superfície de capacidades MCP de 13 ferramentas. O repositório também contém um candidato opcional de coordenação/avaliação Production Next; esses recursos de coordenação, estado de código, recibos de alteração, avaliação e feedback permanecem experimentais e sujeitos aos seus portões de promoção.

Compile a partir do código-fonte

git clone https://github.com/BoxBoxmari/my-pi.git
cd my-pi
pnpm install --frozen-lockfile
pnpm build

Pré-requisitos para desenvolvimento no repositório:

• Node.js v22.6.0+ ou v24 LTS
• pnpm v11.2.2+
• Rust stable é opcional e atualmente relevante apenas para o scaffold de backend nativo adiado

Verificação

# Local code, architecture, boundary, build, tests, gates and smoke verification
pnpm verify

# Unit/integration suite
pnpm test

# SBOM validation
pnpm verify:sbom

# Release admission checks
pnpm bind:evidence
pnpm verify:release

A matriz de CI configurada cobre trilhas Ubuntu, Windows e macOS. Consulte os selos de workflow ao vivo acima para o status atual, em vez de confiar em alegações estáticas neste documento.

Benchmarks

O repositório contém benchmarks sintéticos determinísticos para sobrecarga de stdio MCP, throughput de busca/travessia, amostragem de memória, limites de runtime, comportamento de coordenação, roteamento de impacto, feedback de avaliação e confiabilidade local. As saídas de benchmark são evidências candidatas; alegações de desempenho devem ser interpretadas junto com seus critérios de qualificação e variação de executor.

Production Next (experimental)

Inicie o candidato de coordenação local para um projeto lógico:

my-pi-daemon --workspace /path/to/your/project
my-pi-mcp --workspace /path/to/your/project --coordination

Adicione --evaluation somente quando o plano de avaliação for necessário. O candidato mantém o código-fonte e o estado detalhado do código local, não seleciona modelos nem gera agentes, e não requer um plano de controle hospedado.

Comandos de qualificação relevantes incluem:

pnpm bench:impact-arms
pnpm bench:evaluation-feedback-arms
pnpm dogfood:self-host
pnpm bench:local-reliability
pnpm verify:production-next

Topologia de pacotes

packages/
├── contracts/             # Core interfaces, error codes, fingerprinting
├── workspace-runtime/     # Workspace/path normalization and mutation coordination
├── policy/                # Sensitive-path protection
├── artifact-store/        # Disk-backed spillover artifacts
├── observability/         # Tracing and metrics contracts
├── fs/                    # Hardened filesystem capabilities
├── search/                # Grep/glob traversal
├── hashline/              # Hashline-anchored patch engine
├── ast/                   # Tree-Sitter structural search
├── lsp/                   # Multi-language LSP lifecycle/client
├── vcs/                   # Git-backed status and diff
├── mcp-adapter/           # MCP stdio server adapter
├── host-profiles/         # Host configuration renderers
├── change-runtime/        # Content preconditions and change receipts
├── code-state/            # Filesystem/AST/LSP/VCS code state
├── coordination-client/   # Local daemon client
├── coordination-runtime/  # Work graph, claims, intents, sync
├── coordination-store/    # SQLite event/projection store
├── evaluation-runtime/    # Evaluation and feedback flow
└── impact-engine/         # Bounded impact/routing decisions

O comportamento de ignorar na busca está documentado em docs/SEARCH_IGNORE.md. É uma otimização de travessia, não um substituto para a política de caminhos sensíveis.

Segurança

Antes de usar o modo confiável, leia docs/SECURITY_MODEL.md. Achados de segurança são bem-vindos por meio do processo de reporte documentado do repositório.

Contribuindo

Issues, relatórios de bug reproduzíveis, contraexemplos de benchmark, feedback de integração e pull requests focados são bem-vindos. Se você está avaliando o my-pi em um host de codificação real, inclua o host, SO, versão do Node, perfil de segurança e uma reprodução mínima quando possível.

Licença

MIT — veja LICENSE.