# AyA-MCP v0.2

Nucleo MCP deterministico universal da **AYA / De Bruin Sistemas**.

A v0.2 amplia o projeto para todas as areas da empresa: sistemas web, APIs, SaaS, ecommerce, sites, mobile/desktop, games, IA, fiscal Brasil, pagamentos, comunicacao, dados, seguranca, automacao e infraestrutura.

> Linha pre-1.0. O `package.json` usa `0.2.0` por SemVer/npm; a versao publica e **v0.2**.

## Objetivo

Reduzir o quanto uma LLM precisa lembrar, interpretar e improvisar. Sempre que uma regra importante puder virar codigo, gate, tool, resource, schema, evidence ou policy, o AyA-MCP deve preferir isso a uma instrucao textual solta.

## Integracao com o pacote Agents

O pacote privado `Agentes de IA` e uma fonte funcional da v0.2. Configure:

```bash
AYA_FRAMEWORK_AGENTS_ROOT=/caminho/Agentes-de-IA
```

O MCP inventaria e roteia runtimes, agentes, skills, packs especializados, templates e vendor skills sem carregar milhares de arquivos no contexto.

Conteudo proprietario do Agents **nao e copiado para este repositorio publico**.

### Regras do Agents transformadas em comportamento

- backup antes de editar -> `aya_arquivo_escrever_seguro`;
- log imediato -> `aya_execucao_log_registrar`;
- UTF-8 sem BOM -> `aya_arquivo_encoding_validar`;
- continuidade -> `aya_memoria_agents_inicializar` + checkpoint/handoff;
- evidencia antes de pronto -> `aya_evidencia_*`;
- duas falhas iguais -> `aya_loop_falha_registrar` gera bloqueio;
- roteamento/skills/packs -> `aya_framework_*`;
- governanca do framework -> `aya_framework_governanca_auditar`;
- template-first -> `aya_template_primeiro_planejar`;
- privacidade de modelo -> `aya_modelo_privacidade_avaliar`;
- LLM fraca -> `aya_modelo_perfil_execucao` + toolsets/contexto seletivo.

## Games

Games e dominio de primeira classe.

Engines detectadas inicialmente:

- Godot;
- Unity;
- Unreal Engine;
- Phaser;
- Three.js/WebGL;
- Flutter/Flame;
- libGDX;
- GameMaker;
- Defold;
- Ren'Py;
- LÖVE2D.

Tools:

- `aya_games_detectar_engine`;
- `aya_games_assets_inventariar`;
- `aya_games_validar`;
- `aya_games_checklist`.

A camada de Games sera expandida ainda na v0.2 com integracoes especializadas quando disponiveis.

## Memoria persistente

A v0.2 combina dois modelos:

1. memoria operacional/checkpoint/handoff para continuidade entre LLMs;
2. memoria em grafo do projeto, inspirada no servidor Memory MCP.

Resource:

```text
aya://projeto/memoria-grafo
```

Tools:

- `aya_memoria_grafo_ler`;
- `aya_memoria_grafo_buscar`;
- `aya_memoria_grafo_abrir`;
- `aya_memoria_grafo_upsert`;
- `aya_memoria_grafo_observar`;
- `aya_memoria_grafo_relacionar`;
- `aya_memoria_grafo_remover`.

Segredos sao sanitizados antes de persistir observacoes.

## Codigo e economia de contexto

Inspirado em Serena e `mcp-language-server`, o AyA-MCP ganhou uma camada nativa leve:

- `aya_codigo_outline`;
- `aya_codigo_referencias`;
- `aya_codigo_editar_linhas`;
- `aya_codigo_semantico_planejar`.

O outline/referencias nativos sao deliberadamente **lexicais**. Para definition/rename/diagnostics/call hierarchy semanticamente corretos, preferir LSP/Serena aprovado. O AyA-MCP nao chama regex de LSP.

## Toolsets

Por padrao todas as capacidades sao registradas:

```bash
AYA_TOOLSETS=all
```

Para uma LLM menor, reduza schemas:

```bash
AYA_TOOLSETS=games,codigo,arquivos,memoria,seguranca,evidencias,equipe,agents
```

Toolsets disponiveis:

- `specforge`;
- `agents`;
- `games`;
- `codigo`;
- `arquivos`;
- `memoria`;
- `seguranca`;
- `mcps`;
- `evidencias`;
- `templates`;
- `equipe`.

Use `aya_toolsets_sugerir` para montar um conjunto minimo por tarefa.

## MCPs externos pesquisados

A v0.2 estudou projetos abertos para absorver boas praticas:

- `modelcontextprotocol/servers`;
- `github/github-mcp-server`;
- `docker/mcp-gateway`;
- `oraios/serena`;
- `isaacphi/mcp-language-server`;
- `microsoft/playwright-mcp`;
- `ChromeDevTools/chrome-devtools-mcp`;
- `googleapis/mcp-toolbox`;
- `crystaldba/postgres-mcp`;
- `upstash/context7`;
- `wonderwhy-er/DesktopCommanderMCP`.

Detalhes em `docs/MCPs-ABERTOS-APROVEITADOS-v0.2.md` e `config/mcps-abertos-pesquisados-v0.2.json`.

O AyA nao instala MCP desconhecido automaticamente.

## Seguranca

- workspace fixado em `AYA_WORKSPACE_ROOT`;
- read-only por padrao;
- escrita exige `AYA_MODO_ESCRITA=true`;
- path traversal bloqueado;
- symlinks do framework nao escapam da raiz autorizada;
- `.git`, `node_modules`, `vendor` e vendor skills protegidos de escrita generica;
- backup antes de edicao;
- SHA-256 como precondicao opcional/obrigatoria nas edicoes cirurgicas;
- logs/auditoria sanitizam segredos;
- auditoria estatica procura segredos hardcoded, shell perigoso, `eval`, TLS inseguro, CORS e lockfiles;
- conteudo externo e tratado como dado nao confiavel;
- nenhuma shell irrestrita na v0.2.

## Equipe multiagente universal

`aya_agentes_planejar_equipe` monta papeis conforme o projeto. Alem de Orquestrador, Analista, Arquiteto, Executor, Revisor, Tester, Continuidade e Critico, pode adicionar especialistas em:

- dados;
- backend;
- frontend;
- mobile;
- game design;
- engine/performance;
- seguranca;
- DevOps;
- fiscal Brasil;
- pagamentos;
- comunicacao;
- IA/LLM;
- evidencia/consentimento.

## SpecForge

O SpecForge continua sendo consumidor privilegiado do AyA-MCP, mas o MCP nao depende dele para existir.

As ferramentas REQ/RN/CT/T, rastreabilidade, fila, qualidade, agentes e `aya_validacao_aprovar_saida` ficam no toolset `specforge`.

## Execucao local

```bash
npm install
npm run build
AYA_WORKSPACE_ROOT=/caminho/do/projeto npm start
```

Com Agents:

```bash
AYA_WORKSPACE_ROOT=/caminho/do/projeto \
AYA_FRAMEWORK_AGENTS_ROOT=/caminho/Agentes-de-IA \
npm start
```

## VPS / remoto

```bash
npm run start:http
```

Fora de loopback, configure token e host allowlist conforme `.env.exemplo`.

## Qualidade

```bash
npm run verificar
```

O GitHub Actions executa build TypeScript e testes em cada push/PR.

## Documentos principais

- `docs/V0.2-ESCOPO.md`
- `docs/INTEGRACAO-AGENTS.md`
- `docs/GAMES.md`
- `docs/MCPs-ABERTOS-APROVEITADOS-v0.2.md`
- `docs/SEGURANCA.md`
- `docs/ROADMAP.md`
- `CHANGELOG.md`
- `VERSIONAMENTO.md`