Produto

Integração com clientes MCP

O PromptFlowEngine fala o Model Context Protocol, então qualquer cliente MCP (modo agente do GitHub Copilot, Claude Desktop, Claude Code, Cursor ou o seu próprio agente) pode chamar o motor como ferramentas. Seu assistente pode então verificar, reestruturar e sanitizar um prompt como uma etapa do próprio trabalho, em vez de você fazer isso à mão.

Uma observação sobre os termos: o que você instala é um servidor MCP (@promptflow/mcp-server v2.1.0, nome do servidor promptflow-engine). Sua ferramenta de IA é o cliente MCP que se conecta a ele.

Configuração para Claude Code, Windsurf e Gemini CLI, um exemplo de cliente TypeScript e solução de problemas: Conectar o PromptFlowEngine.

Como ele se conecta

conexão

MCP client (Copilot, Claude, Cursor, your agent)
   │  spawns a local process and talks JSON-RPC over stdio
   ▼
promptflow-mcp  (node packages/mcp-server/dist/bin.js)
   │  validates arguments, runs the engine in-process
   ▼
@promptflow/engine   no network, no model calls, no files read

O transporte é apenas stdio. O servidor roda na sua máquina como processo filho do cliente, lê somente os argumentos que recebe e não faz chamadas de rede.

Autenticação

Não é necessária nem há suporte: não existe chave de API, conta nem token. O acesso é controlado pelo seu sistema operacional, já que só um processo que você inicia pode falar com o servidor pela entrada e saída padrão. Não há endpoint MCP hospedado ou HTTP; para uso remoto, chame a API HTTP.

Configurar

Compile-o a partir de uma cópia do repositório do PromptFlowEngine (a publicação no npm está pendente) e aponte seu cliente para dist/bin.js:

shell

pnpm --filter @promptflow/engine build && pnpm --filter @promptflow/mcp-server build

VS Code / Copilot: .vscode/mcp.json

{
  "servers": {
    "promptflow": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/checkout/packages/mcp-server/dist/bin.js"]
    }
  }
}

Claude Desktop, Cursor e outros clientes

{
  "mcpServers": {
    "promptflow": { "command": "node", "args": ["/absolute/path/to/checkout/packages/mcp-server/dist/bin.js"] }
  }
}

A extensão do VS Code inclui o mesmo servidor e escreve a primeira entrada para você.

Variável de ambiente	Padrão	Finalidade
`PROMPTFLOW_MCP_MAX_PROMPT_CHARS`	`100000`	Máximo de caracteres por argumento de texto (limite absoluto de 2.000.000).
`PROMPTFLOW_MCP_LOG`	não definida	`debug` registra no stderr o nome da ferramenta, o tamanho da entrada, o resultado e a duração. Nunca o conteúdo.

Recursos: ferramentas (19)

Ferramenta	Descrição
`optimize_prompt`	Optimize a prompt with deterministic, verified transforms (duplicates, filler, optional sections). Every candidate is checked to preserve all sentences, requirements, code, and variables; the original is kept if nothing is better. Returns the selected prompt, token savings, quality score, and what changed.
`optimize_prompt_pipeline`	Run the optimization pipeline and return per-stage results plus token and estimated cost metrics, in the result shape used by the PromptFlow VS Code extension.
`compress_prompt`	Remove exact duplicate sentences and extra whitespace without rewriting any wording.
`validate_prompt`	Check a prompt for missing objective or output format, ambiguity, conflicting instructions, duplicates, prompt-injection patterns, secrets, and undelimited variables. isValid is false only when a critical issue exists.
`estimate_tokens`	Count tokens and estimate input cost for a model. "exact" is true only for OpenAI models with a loaded tokenizer; other providers are approximate. Costs are estimates from a reference price table.
`analyze_prompt`	Detect intent, task type, technical domain, requested output, requirements, and entities (languages, frameworks, file paths, identifiers).
`extract_entities`	Extract languages, frameworks, libraries, cloud platforms, services, technologies, file paths, identifiers, URLs, and commands.
`summarize_context`	Extractive summary: the first N unique, non-empty sentences of a context block, in order. Does not rank or rewrite.
`score_prompt`	Score prompt quality 0-100: 100 minus a penalty per issue (critical 30, warning 10, info 3; capped at 50 with any critical issue), with per-dimension scores and suggestions.
`evaluate_prompt`	Full quality report: overall score, grade, eight quality dimensions with the checks that failed, and every finding with why it matters and how to fix it.
`compare_prompts`	Compare two prompts: token and estimated cost delta, quality delta per dimension, and which findings were resolved or introduced.
`scan_prompt_security`	Prompt-injection risk (0-100, signature-based, with threat ids), sensitive-data counts by category, undelimited template variables, and destructive operations. Never returns detected secret values.
`scan_sensitive_data`	Scan text for credentials, cloud secrets, and PII with local deterministic detectors. Returns offsets and per-category counts, never the sensitive values.
`sanitize_prompt`	Replace detected sensitive data with placeholders such as [REDACTED_API_KEY]. Returns the sanitized text and counts, never the original values. Use before sending a prompt to an external model.
`restructure_prompt`	Turn a loosely written request into a sectioned engineering prompt: Role, Objective, Context, Requirements, Constraints, Edge cases, Testing, Acceptance criteria, Expected output. Only sections with content appear. The author's clauses are kept and reordered; for software tasks, fixed engineering guidance chosen by intent and topic is added, and every line is labeled "prompt" or "engine" so additions can be reviewed. Set scaffold=false to reorganize without adding guidance.
`convert_structured_payload`	Convert a JSON payload to TOON (Token-Oriented Object Notation) and say whether to use it. Returns token counts for pretty JSON, compact JSON and TOON, a round-trip check (the TOON must decode back to the same value), and the recommendation: "toon" only when it round-trips and saves at least 5 % over compact JSON, otherwise "json". Lossless or it keeps JSON.
`simulate_cost`	Simulate what a prompt costs across models at a request volume, from catalog list prices (labelled simulated, never a bill). Optionally optimizes the prompt first and reports hypothetical savings. Flags models whose context window is too small.
`analyze_context_budget`	Measure the context sources you intend to send with a prompt: tokens and share per source, context-window usage with an output reserve, sensitive data (categories and counts only), instruction-like text in retrieved sources, and duplicates. Reads only the text passed in; never reads files.
`run_prompt_tests`	Run a regression suite against a prompt. Assertions check the prompt (contains, not_contains, matches, max_tokens, min_quality, no_finding, max_severity, has_variables, max_injection_risk, no_sensitive_data, output_format) and, when a case carries a recorded model response, the response (response_valid_json, response_has_keys, response_contains, response_max_chars). With baseline_prompt, also runs the suite on the baseline and lists cases that regressed. No model is called.

Todas as ferramentas são anotadas como somente leitura e idempotentes. As onze primeiras mantêm exatamente os campos de resultado que tinham na extensão 1.5.x, então as configurações de agentes existentes continuam funcionando.

Recursos e prompts

promptflow://rules: o catálogo de regras, as dimensões e as penalidades de pontuação.
promptflow://models: modelos, codificações de tokens e preços de referência.
Prompt review-prompt: pede ao assistente que avalie e otimize um prompt, com o prompt envolvido em tags como dado.

Exemplo

Em um chat com um agente, peça em linguagem comum e o cliente escolhe a ferramenta:

você

Use promptflow to restructure this before you start:
"fix login issue and make google login work and don't break anything"

tools/call enviado pelo cliente

{
  "name": "restructure_prompt",
  "arguments": { "prompt": "fix login issue and make google login work and don't break anything" }
}

resultado (resumido)

{
  "restructuredPrompt": "## Role\nAct as a senior software engineer.\n\n## Objective\nFix login issue and make Google login work.\n…",
  "intent": "debugging",
  "topics": ["authentication"],
  "counts": { "prompt": 4, "engine": 20, "codebase": 0 }
}

Para testar sem um cliente, envie JSON-RPC ao processo por um pipe:

shell

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"estimate_tokens","arguments":{"prompt":"Hello, world!","model":"gpt-4o"}}}' \
  | node packages/mcp-server/dist/bin.js

Erros e segurança

Os argumentos são validados por um esquema. Argumentos inválidos ou grandes demais retornam um erro de ferramenta (isError) com o motivo, e não um erro de protocolo, para que os agentes possam corrigir e tentar de novo.
Nenhuma ferramenta retorna valores secretos detectados: os resultados de dados sensíveis trazem apenas categorias e posições.
O texto de prompt passado a uma ferramenta é tratado como dado. O servidor nunca o executa, e o template review-prompt o envolve em tags para o modelo.
O servidor não tem ferramentas de arquivo, shell nem rede, então um agente comprometido por injeção de prompt não consegue usá-lo para alcançar nada.