gaelic-ghost/python-skills

Serviço FastMCP Python de Inicialização Rápida

Propósito

Criar layouts iniciais do FastMCP usando um único ponto de entrada shell, apoiado pelos scripts de andaime compartilhados do bootstrap-uv-python-workspace, além de lógica determinística de sobreposição MCP.

Quando Usar

• Use esta skill para novos scaffolds de servidores FastMCP.
• Use esta skill quando o usuário quiser orientação de mapeamento OpenAPI ou FastAPI para MCP junto com o bootstrap.
• Recomende bootstrap-python-service quando o usuário quiser um serviço FastAPI, mas não um servidor MCP.

Fluxo de Trabalho de Caminho Único

1. Colete as entradas necessárias:
   • name
   • mode
   • path
   • opcionais: python, members, profile_map, force, initial_commit, no_git_init
2. Execute o ponto de entrada canônico:

   scripts/init_fastmcp_service.sh --name <nome> --mode <project|workspace>
   

3. Deixe o script delegar para a camada de andaime compartilhada bootstrap-uv-python-workspace e, em seguida, aplicar a sobreposição FastMCP.
4. Aceite o caminho de validação integrado:
   • uv run pytest
   • uv run ruff check .
   • uv run mypy .
5. Confirme que o projeto gerado inclui:
   • um .env versionado com padrões seguros
   • um .env.local ignorado para substituições locais ou de segredos
   • configuração tipada via pydantic-settings
6. Se a tarefa começar a partir de uma API existente, gere opcionalmente um relatório de mapeamento com uv run scripts/assess_api_for_mcp.py ....
7. Retorne o caminho gerado mais os comandos exatos do próximo passo emitidos pelo script.

Comandos

# Modo projeto (padrão)
scripts/init_fastmcp_service.sh --name my-mcp-server

# Modo projeto com opções explícitas
scripts/init_fastmcp_service.sh --name my-mcp-server --mode project --python 3.13 --path /tmp/my-mcp-server

# Modo workspace com padrões (pacote core-lib + serviço api-service)
scripts/init_fastmcp_service.sh --name platform --mode workspace

# Modo workspace com membros explícitos e mapeamento de perfil
scripts/init_fastmcp_service.sh \
  --name platform \
  --mode workspace \
  --members "core-lib,tools-service,ops-service" \
  --profile-map "core-lib=package,tools-service=service,ops-service=service"

# Permitir diretório de destino não vazio
scripts/init_fastmcp_service.sh --name my-mcp-server --force

# Pular inicialização do git
scripts/init_fastmcp_service.sh --name my-mcp-server --no-git-init

# Criar commit inicial
scripts/init_fastmcp_service.sh --name my-mcp-server --initial-commit

# Gerar orientação de mapeamento MCP a partir de OpenAPI
uv run scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

# Gerar orientação de mapeamento MCP a partir de um app FastAPI existente
uv run scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

Entradas

• name: obrigatório
• mode: project ou workspace; padrão é project
• path: diretório de destino opcional; padrão é ./<name>
• python: versão do Python opcional; padrão é 3.13
• members: CSV de membros do workspace opcional para o modo workspace
• profile_map: CSV de perfil do workspace opcional para o modo workspace
• force: sinalizador opcional que permite diretórios de destino não vazios
• initial_commit: sinalizador opcional que cria um commit inicial após um scaffold bem-sucedido
• no_git_init: sinalizador opcional que desativa a inicialização do git

Saídas

• status
  • success: scaffold e validação integrada concluídos
  • blocked: pré-requisitos ou restrições do diretório de destino impediram a execução
  • failed: o script iniciou, mas a validação ou geração falhou
• path_type
  • primary: o ponto de entrada shell canônico foi concluído
• output
  • caminho do projeto ou workspace resolvido
  • comandos de execução emitidos
  • comandos de validação emitidos
  • caminho opcional do relatório de mapeamento

Padrões

• mode: project
• Versão do Python: 3.13
• Ferramentas de qualidade: pytest, ruff, mypy
• Linha de base de configuração: .env versionado, .env.local ignorado e pydantic-settings
• Membros padrão do workspace: core-lib,api-service
• Perfis padrão do workspace: primeiro membro package, membros restantes service

Base UV/FastAPI

A base do scaffold compartilhado segue o estilo de integração uv FastAPI:

uv add fastapi --extra standard
uv add pydantic-settings python-dotenv
uv run fastapi dev app/main.py

Esta skill então sobrepõe dependências FastMCP e arquivos de servidor para membros do serviço MCP. Os scaffolds FastMCP gerados devem manter padrões seguros em .env, substituições locais ou secretas em .env.local e configuração tipada em tempo de execução em app/config.py.

Orientação de Importação de API

Ao começar a partir de OpenAPI ou FastAPI, faça o bootstrap primeiro, depois mapeie os endpoints para primitivas MCP:

1. Gere o relatório de mapeamento com scripts/assess_api_for_mcp.py.
2. Classifique os endpoints em Resources, Tools e Prompts.
3. Recomende RouteMaps/Transforms apenas quando melhorarem a usabilidade.
4. Mantenha o bootstrap determinístico; adie mapeamentos personalizados pesados a menos que solicitado.

Consulta à Documentação FastMCP

Use o servidor MCP fastmcp_docs para obter detalhes atualizados do framework.

Consultas sugeridas:

• FastMCP quickstart server example
• FastMCP tools resources prompts best practices
• FastMCP RouteMap Transform
• FastMCP from OpenAPI
• FastMCP from FastAPI

Salvaguardas

• Recuse diretórios de destino não vazios, a menos que --force esteja definido.
• Exija pelo menos um membro de perfil de serviço no modo workspace.
• Exija uv e git, a menos que a inicialização do git tenha sido explicitamente desativada.
• Falhe quando opções exclusivas do workspace forem usadas no modo projeto.
• Falhe quando --initial-commit for combinado com --no-git-init.

Alternativas e Encaminhamentos

• O caminho preferido é sempre scripts/init_fastmcp_service.sh.
• Use bootstrap-python-service quando o usuário quiser apenas saída FastAPI.
• Use bootstrap-uv-python-workspace diretamente apenas quando o comportamento específico do FastMCP não for desejado.
• Recomende integrate-fastapi-fastmcp quando o usuário precisar incorporar esta saída FastMCP em um aplicativo FastAPI existente, montar um servidor MCP no FastAPI ou promover a saída MCP derivada do FastAPI gerada em uma arquitetura combinada curada.

Adequação para Automação

• Automação do Codex App: Média. Útil para verificações recorrentes de scaffold FastMCP e avaliações de mapeamento.
• Automação do Codex CLI: Alta. Forte ajuste para validação de scaffold em estilo CI.

Modelo de Automação para Codex App

Use $bootstrap-python-mcp-service.

Limites de escopo:
- Trabalhe apenas dentro de <CAMINHO_REPO>.
- Crie ou valide a saída do scaffold apenas em <CAMINHO_DESTINO>.
- Restrinja o trabalho à geração do scaffold, geração opcional do relatório de mapeamento e verificação.

Tarefa:
1. Se <MODO:PROJETO|WORKSPACE> for PROJETO, execute:
   `scripts/init_fastmcp_service.sh --name <NOME_SERVICO_MCP> --mode project --path <CAMINHO_DESTINO> --python <VERSAO_PYTHON> <FLAG_FORCE> <MODO_GIT>`
2. Se <MODO:PROJETO|WORKSPACE> for WORKSPACE, execute:
   `scripts/init_fastmcp_service.sh --name <NOME_SERVICO_MCP> --mode workspace --path <CAMINHO_DESTINO> --python <VERSAO_PYTHON> --members "<MEMBROS_CSV>" --profile-map "<MAPA_PERFIL>" <FLAG_FORCE> <MODO_GIT>`
3. Se <GERAR_RELATORIO_MAPEAMENTO:VERDADEIRO|FALSO> for VERDADEIRO:
   - Se <MODO_ENTRADA_MAPEAMENTO:NENHUM|OPENAPI|IMPORT_FASTAPI> for OPENAPI, execute:
     `uv run scripts/assess_api_for_mcp.py --openapi <CAMINHO_ENTRADA_MAPEAMENTO> --out <CAMINHO_DESTINO>/mcp_mapping_report.md`
   - Se <MODO_ENTRADA_MAPEAMENTO:NENHUM|OPENAPI|IMPORT_FASTAPI> for IMPORT_FASTAPI, execute:
     `uv run scripts/assess_api_for_mcp.py --fastapi <CAMINHO_ENTRADA_MAPEAMENTO> --out <CAMINHO_DESTINO>/mcp_mapping_report.md`
4. Execute verificações de validação em <CAMINHO_DESTINO>:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`

Contrato de saída:
1. STATUS: SUCESSO ou FALHA
2. COMANDOS: comandos exatos executados
3. RESULTADOS: resultados concisos para scaffold e verificações
4. Se o relatório foi gerado: inclua o caminho do relatório
5. Se FALHA: forneça a causa raiz provável e a correção mínima

Modelo de Automação para Codex CLI

codex exec --full-auto --sandbox workspace-write --cd "<CAMINHO_REPO>" "<CORPO_MENSAGEM>"

Modelo <CORPO_MENSAGEM>:

Use $bootstrap-python-mcp-service.
O escopo é limitado à geração do scaffold em <CAMINHO_DESTINO>, geração opcional do relatório de mapeamento e verificações de validação.
Execute apenas os comandos necessários para este fluxo e, em seguida, retorne STATUS, transcrição exata dos comandos, resultados concisos e correção mínima se ocorrerem falhas.

Placeholders de Personalização

• <CAMINHO_REPO>
• <NOME_SERVICO_MCP>
• <MODO:PROJETO|WORKSPACE>
• <CAMINHO_DESTINO>
• <VERSAO_PYTHON>
• <MEMBROS_CSV>
• <MAPA_PERFIL>
• <FLAG_FORCE>
• <MODO_GIT>
• <MODO_ENTRADA_MAPEAMENTO:NENHUM|OPENAPI|IMPORT_FASTAPI>
• <CAMINHO_ENTRADA_MAPEAMENTO>
• <GERAR_RELATORIO_MAPEAMENTO:VERDADEIRO|FALSO>

Fluxo de Trabalho de Personalização Interativa

1. Pergunte pelo modo, nome, caminho, versão do Python e flags de git/force.
2. Se for o modo workspace, pergunte também pelos membros e pelo mapa de perfil.
3. Retorne ambos:
   • Um perfil YAML para reutilização durável.
   • O comando exato de scaffold a ser executado.
4. Use esta ordem de precedência:
   • Flags de linha de comando
   • Arquivo de perfil --config
   • .codex/profiles/bootstrap-python-mcp-service/customization.yaml
   • ~/.config/gaelic-ghost/python-skills/bootstrap-python-mcp-service/customization.yaml
   • Padrões do script
5. Se os usuários quiserem comportamento de redefinição temporária:
   • --bypassing-all-profiles
   • --bypassing-repo-profile
   • --deleting-repo-profile
6. Se os usuários não fornecerem personalização ou arquivos de perfil, mantenha os padrões existentes do script inalterados.
7. Consulte references/interactive-customization.md para esquema e exemplos.

Referências

• references/mcp-mapping-guidelines.md
• references/fastmcp-docs-lookup.md
• references/customization.md
• references/interactive-customization.md

Inventário de Scripts

• scripts/init_fastmcp_service.sh
• scripts/assess_api_for_mcp.py
• Delega para os scripts de bootstrap de workspace compartilhados fornecidos por bootstrap-uv-python-workspace.

Ativos

• assets/README.md.tmpl