poml-mcp

MCP (Model Context Protocol) server to improve and structure prompts using POML best practices, optimized so code agents can solve tasks with more context and reliability.

• 

• ✨ Goal: clear prompts + executable POML for reproducible flows.

• 🧠 Works for LLMs/Agents and humans (documentation and action).

• 🛡️ Stable approach: minimally sufficient, robust POML subset.

• Provides enhance_prompt to improve briefs and generate POML.

• Provides poml_translate to discover .md/configs and convert them to .poml with professional templates (task, output-format, cp, optional stepwise, aggregated index.poml).

• Exposes .poml examples as dynamic resources poml-example://{name}.

📚 Table of Contents

• Why this MCP (vision and goal)
• Flow Diagram (high-level)
• Tools Summary
• YAML Configuration (profiles and triggers)
• LLM Auto-configuration
• Quick usage (Inspector CLI)
• POML Integration (optional rendering)
• Gemini Integration (ADK + Gemini CLI)
• Registered tools
• Conversion of Windsurf Workflows (.windsurf/workflows) to POML
• CI (GitHub Actions)
• Environment variables
• Design analysis and decisions
• Development
• Roadmap and Backlog
• License

Why this MCP (vision and goal)

This server pursues two complementary goals:

1. Standardize prompts in POML so they are auditable, composable, and executable by agents.
2. Reduce initial friction: discover repository documentation/configuration and convert it into POML ready to operate.

Benefits:

• ✅ Clarity and consistency: prompts with explicit sections (<task>, <output-format>, Style/Include/Constraints).
• 🔁 Reproducibility: reusable POML flows in CI/IDE (Windsurf) or agents.
• 📈 Continuous improvement: automated tests (mcp-jest), documented conventions, and YAML configuration.

Flow Diagram (high-level)

flowchart LR
  A[User/Agent] -- user_request --> B[enhance_prompt]
  B -- enhanced + POML --> C[Client/IDE]
  C -- optional: read/render --> D[(POML lib)]
  A2[Repo] -- .md / configs --> E[poml_translate]
  E -- discover/plan/apply --> F[.poml outputs + index]
  A3[Repo] -- error signals --> G[incident_discovery]
  G -- plan/apply --> H[Triage POML]

Tools Summary

| Tool | Purpose | Modes | Key args | Output | |---|---|---|---|---| | enhance_prompt | Improve a brief and generate a POML template | — | user_request, audience, style, output_format, include, constraints | enhanced, poml, rendered? | | poml_translate | Discover/plan/apply .poml conversions | discover/plan/apply | includeGlobs, excludeGlobs, selections, outputDir, stepwise, aggregateIndex | discovered, proposals, wrote, notes, warnings | | incident_discovery | Discover incident signals and a triage plan | discover/plan/apply | query, errorTerms, includeGlobs, maxFiles | findings or poml | | windsurf_to_poml | Alias for Windsurf workflows | discover/plan/apply | selections, outputDir, aggregateIndex, indexName | same as poml_translate | | auto_configure | LLM-driven auto-configuration | detect/plan/apply | preferLanguage, projectKind | config, notes, warnings | | generate_docs | Scaffold PLANNING.md, TASK.md, AI_RULES.md | plan/apply | outputDir, planning, task, rules, overwrite, ideRules[], projectName, format?, includePrpSkeleton? | proposals, wrote, warnings, notes | | generate_prp | Generate Product Requirements Prompt (PRP) from INITIAL and context | apply | initialPath, outputDir, format, docsLinks[], examples[], overwrite, projectName? | wrote, warnings, notes | | execute_prp | Parse PRP and output execution steps | plan/apply | prpPath, mode, root? | steps, warnings, notes | | pm_sync | Sync docs/TASK.md with GitHub Issues | plan/apply | provider=github, repo, token?, docsPath?, labels[] | proposals, wrote, warnings, notes |

Recommended POML Workflow (for agents)

Purpose

Use POML MCP to turn free‑text prompts into structured POML for reliable, portable agent execution. Keep team docs human‑friendly in Markdown; use POML when you want executable, composable prompts.

Where POML fits vs Markdown

• Docs (human): PLANNING.md, TASK.md, AI_RULES.md remain Markdown.
• Prompts (agent/executable): POML via tools like enhance_prompt, poml_translate, windsurf_to_poml, generate_prp --tool-arg format=poml|both.

End‑to‑end flow

1. Send free‑form prompt → enhance_prompt.
2. You receive: enhanced (text), poml (structure), rendered? (text rendered from POML).
3. Consume in your agent:
   • If the agent supports POML: pass poml directly.
   • If not: use rendered or render client-side with a POML library.
4. Optional: convert workflows .windsurf/workflows/*.md to .poml with windsurf_to_poml/poml_translate for automation.

Agent integration (quick)

• Case A (native POML): send the poml field from enhance_prompt.
• Case B (text-only): use rendered. If missing, render poml to text using a POML renderer.

Examples

# 1) Enhance a prompt and obtain POML
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call \
  --tool-name enhance_prompt --tool-arg user_request="Generate a migration plan to PostgreSQL"
# 2) Convert Windsurf workflows to POML
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call \
  --tool-name windsurf_to_poml --tool-arg mode=plan --tool-arg selections=.windsurf/workflows/generate-docs.md
# 3) Generate a PRP also in .poml
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call \
  --tool-name generate_prp --tool-arg outputDir=PRPs --tool-arg format=both

Repo pointers

• POML Conventions: spec/POML_CONVENTIONS.md
• Tools: enhance_prompt, poml_translate, windsurf_to_poml, generate_prp in index.mjs
• Workflows: .windsurf/workflows/

Global AI Rules recommendation (auto‑generated)

generate_docs now produces AI_RULES.md with rules to:

• Prefer POML-structured prompts via the POML MCP.
• Use enhance_prompt to transform free text into POML.
• When an agent does not support POML, use the MCP rendered output.

Requirements

• Node.js 18+
• npm or pnpm

Installation (options)

A) Via npm (recommended for Windsurf/Cascade)

Publish this package to npm (see “Publishing” section) and use npx in your mcp_config.json:

{
  "mcpServers": {
    "poml-mcp": {
      "command": "npx",
      "args": ["-y", "<package-name>"]
    }
  }
}

Short alias for dev:

{
  "mcpServers": {
    "poml-dev": {
      "command": "node",
      "args": ["E:/scripts-python/POML-MCP/index.mjs"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Notes:

• Replace <package-name> with the real npm name (e.g., poml-mcp).
• Windsurf looks for this file at ~/.codeium/mcp_config.json.

Alias (short name): you can also register the server key as poml to keep the UI concise, while still installing poml-mcp:

{
  "mcpServers": {
    "poml": {
      "command": "npx",
      "args": ["-y", "poml-mcp"]
    }
  }
}

B) Local (development)

At project root:

npm install
npm start

To use it in Windsurf via stdio, you can point to index.mjs with an absolute path from mcp_config.json on Windows/macOS/Linux:

{
  "mcpServers": {
    "poml-dev": {
      "command": "node",
      "args": ["E:/scripts-python/POML-MCP/index.mjs"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Tip: Locally, prefer using npm (Option A) once published, to avoid absolute paths.

🧩 YAML Configuration (profiles and triggers)

The server optionally loads poml-mcp.config.yml from the project root (or poml-mcp.config.yaml). This file lets you:

• Define profiles (profiles) with defaults for enhance_prompt.
• Enable triggers based on user_request content (includes/regex) that dynamically adjust style/include/constraints.

Example file: poml-mcp.config.example.yml.

Minimal example:

profiles:
  default:
    enhance:
      audience: "Technical Team"
      style: "Professional and concise"
      constraints:
        - "Do not include sensitive data"
        - "Cite evidence when using numbers"
  error:
    enhance:
      audience: "On-call / SRE"
      include:
        - "Incident context"
        - "Steps to reproduce"
        - "Relevant logs and stack traces"
      output_format: |
        Summary
        Evidence
        Impact
        Next steps
        Owner
triggers:
  - match:
      includesAny: ["error", "exception", "stack trace", "traceback"]
    profile: error
    enhance:
      style: "Technical and actionable"

🤖 LLM Auto-configuration

The first-run flow can be 100% LLM-assisted using the auto_configure tool:

• detect mode: detects project type via signals (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, *.csproj|*.sln).
• plan mode: generates an onboarding POML to review/adjust.
• apply mode: writes initial files (non-destructive):
  • poml-mcp.config.yml (default profiles/triggers).
  • Onboarding workflow at .windsurf/workflows/llm-auto-config.md.

Examples with Inspector:

npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name auto_configure --tool-arg mode=detect
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name auto_configure --tool-arg mode=plan
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name auto_configure --tool-arg mode=apply

Notes:

• If your repo does not yet contain .windsurf/workflows/, the workflow is created to guide you in the IDE.
• You can force language or type with preferLanguage and projectKind.

Quick usage (Inspector CLI)

List tools and run basic checks without writing your own client:

npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/list
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name enhance_prompt --tool-arg user_request=Hello
# Discover/plan/apply translation to POML
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name poml_translate --tool-arg mode=discover
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name poml_translate --tool-arg mode=plan
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name poml_translate --tool-arg mode=apply --tool-arg outputDir=poml-output --tool-arg stepwise=true --tool-arg aggregateIndex=true

You also have npm scripts:

npm run test:inspector:tools
npm run test:inspector:enhance
npm run test:inspector:poml:discover
npm run test:inspector:poml:plan
npm run test:inspector:poml:apply

🔎 Sequence Diagram (client-server interaction)

sequenceDiagram
  participant IDE as IDE/Inspector
  participant MCP as POML (stdio)
  participant FS as Filesystem

  IDE->>MCP: tools/list
  MCP-->>IDE: [enhance_prompt, poml_translate, incident_discovery, ...]
  IDE->>MCP: tools/call enhance_prompt { user_request }
  MCP-->>IDE: structuredContent { enhanced, poml, rendered? }
  IDE->>MCP: tools/call poml_translate { mode: apply, outputDir }
  MCP->>FS: write *.poml (+ index.poml if aggregate)
  MCP-->>IDE: structuredContent { wrote, notes, warnings }

POML Integration (optional rendering)

The server attempts to integrate the actual POML library to render to text:

• Dynamic import of ../packages/poml/index.js or ../packages/poml/dist/index.js.
• If no JS build is available, rendered is omitted in the output.
• To enable rendering, build the POML library or provide an accessible JS entry.

🤝 Gemini Integration (ADK + Gemini CLI)

This server supports Google's “vibe building” flow (ADK + Gemini CLI) and uses the llms-full.txt context file from the official ADK repo.

Reference: “Simplify your Agent "vibe building" flow with ADK and Gemini CLI” (Google Developers Blog)

Suggested steps:

• Step 0: Download llms-full.txt from google/adk-python and place it in your working directory.
• Step 1: Ideate a plan with Gemini CLI, referencing @llms-full.txt so the CLI understands ADK primitives and suggests the right structure.
• Step 2: Convert the plan to an ADK agent (the CLI generates ADK code/requirements and tools like github_tools.py).
• Step 3/4: Test and iterate within the CLI loop.
• Step 5: Repeat and improve with short cycles.

How it fits with poml-mcp:

• Design strong briefs with enhance_prompt, producing clear POML (task/output-format/style/include/constraints) you can port to your ADK agent system prompts/instructions.
• Discover docs/configs with poml_translate and convert them to .poml to provide structured context to Gemini CLI or as a base specification.
• Auto-onboarding with auto_configure: generate initial config and an onboarding workflow so you can iterate quickly with Gemini CLI in your IDE.
• Windsurf: translate .windsurf/workflows/*.md to executable POML; use it as a contract for what the agent should automate/build.

Recommended YAML profile snippet for Gemini projects:

profiles:
  gemini:
    enhance:
      audience: "Agent Team (ADK)"
      style: "Clear, ADK-idiomatic, actionable steps"
      constraints:
        - "If llms-full.txt exists, use it as the framework guide"
        - "Avoid implicit deps; cite ADK modules/classes explicitly"

ADK Overview and Best Practices

The Agent Development Kit (ADK, Python) is a code‑first toolkit for building, evaluating, and deploying sophisticated AI agents with explicit control over tools, orchestration, and state.

• When to use ADK

  • Complex multi‑step tasks and multi‑agent handoffs.
  • Reliability (timeouts, retries, rate limiting) and governance.
  • Production use: background workers, APIs, observability, persistence.

• Core building blocks

  • Agents (behavior + model + tools), tools as first‑class functions.
  • Runner and SessionService to execute flows and persist state.
  • Orchestrator patterns and agent handoff (transfer_to_agent).

• Best practices

  • Strong system prompts/guardrails; follow spec/POML_CONVENTIONS.md when generating instructions.
  • Deterministic, idempotent tools with validated inputs and typed outputs.
  • Resilience: retries/backoff, timeouts, rate limits, circuit breakers.
  • Persist state (sessions, checkpoints) for long workflows.
  • Observability: structured logs, metrics, traces.
  • Isolation: Python venv/conda; secrets from .env; containerize for prod.

Using ADK with Gemini (Recommended Workflow)

Pair Gemini CLI (for ideation/generation/iteration) with ADK (for runtime robustness):

1. Place llms-full.txt (from google/adk-python) at the repo root.
2. In Gemini CLI, ideate a plan referencing @llms-full.txt so the CLI understands ADK primitives.
3. Ask the CLI to convert the plan to ADK code (Python modules, tools, requirements).
4. Run locally, test, and iterate quickly inside the CLI loop.
5. Promote to a service/worker (FastAPI, cron/queues). Add persistence/observability.

Example use cases:

• GitHub triage: orchestrator agent + repo tools; background worker consumes a queue of issues.
• Incident response: parsing logs, root‑cause analysis sub‑agents, remediation proposal; persisted sessions.
• Code refactors: analyze → propose diffs → apply with review “hold points.”

Gemini CLI‑only configuration (no ADK required)

You can use Gemini CLI with this MCP without ADK installed in the project. Configure MCP servers in ~/.gemini/settings.json:

"poml": {
  "command": "npx",
  "args": ["-y", "poml-mcp"],
  "env": { "POML_ENABLE_EXAMPLES": "1" },
  "trust": false
}

Local/dev alternative:

"poml-dev": {
  "command": "node",
  "args": ["E:/scripts-python/POML-MCP/index.mjs"],
  "env": { "NODE_ENV": "production", "POML_ENABLE_EXAMPLES": "1" },
  "trust": false
}

Tips:

• Run in the project directory (gemini).
• Use server tools: enhance_prompt, poml_translate, incident_discovery, windsurf_to_poml.
• Non‑interactive: gemini -p "Summarize architecture".
• Include directories: --include-directories src,docs.
• Pick model: -m gemini-2.5-flash (adjust as needed).

Background agents and multi‑agent patterns (viable architecture)

Gemini CLI is a developer assistant, not a background scheduler. Run agents as services/workers:

• Python ADK service: FastAPI + Runner + SessionService; deploy via Docker/PM2/k8s/Cloud Run; schedule with cron/queues (Pub/Sub, SQS, Redis).
• Node service (no ADK): use the Gemini JS SDK; same service/worker patterns.
• MCP integration: expose management tools to control/observe background agents.

Multi‑agent orchestration:

• Orchestrator agent with sub‑agents and explicit handoffs.
• Persist state; add timeouts and retries between handoffs.

Proposed sibling MCP: background‑orchestrator‑mcp

Purpose: manage background agents/services via MCP so IDE/CLI can control them safely.

• Tools (initial): agents/list, agents/start, agents/stop, agents/submit_task, agents/logs, agents/health (optional agents/scale).
• Transports: local spawn/PM2/systemd and/or remote HTTP/queues.
• Security: tokens, allowlists; never expose raw shell without confirmations.
• Complements poml-mcp for end‑to‑end build + operate in IDE.

Community & Support

• Code of Conduct: CODE_OF_CONDUCT.md
• Contributing: CONTRIBUTING.md
• Security Policy: SECURITY.md
• Support: SUPPORT.md
• Changelog: CHANGELOG.md

References

• Google Developers Blog: Simplify your Agent “vibe building” flow with ADK and Gemini CLI
  • https://developers.googleblog.com/en/simplify-agent-building-adk-gemini-cli/
• ADK Python
  • Repo: https://github.com/google/adk-python
  • llms-full.txt: https://github.com/google/adk-python/blob/main/llms-full.txt
  • Multi‑agent FastAPI discussion: https://github.com/google/adk-python/discussions/1241
  • Handoff behavior: https://github.com/google/adk-python/issues/714
  • Tool use in sub_agents: https://github.com/google/adk-python/issues/53
• Gemini CLI
  • Repo: https://github.com/google-gemini/gemini-cli
  • Authentication: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/authentication.md
  • Configuration: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md
  • MCP servers: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
  • Sandboxing: https://github.com/google-gemini/gemini-cli/blob/main/docs/sandbox.md

🧪 Useful scripts (npm)

| Script | Description | |---|---| | start | Starts the MCP server over stdio | | test | Simple test client (client.mjs) | | test:inspector:* | Examples with Inspector (tools/list, enhance, translate) | | test:mcpjest:* | MCP protocol tests (CLI and Node API) | | test:ci | Combined suite for CI |

Registered tools

enhance_prompt

• Description: Improves a brief and returns an enhanced prompt + POML template.
• Input (Zod raw shape):
  • user_request?: string (default "Test request")
  • audience?: string
  • style?: string
  • target_language?: string
  • domain?: string
  • output_format?: string (one item per line)
  • include?: string[]
  • constraints?: string[]
  • examples?: string[]
• Output (outputSchema):
  • enhanced: string
  • poml: string
  • rendered?: string
  • messages?: any[]

poml_translate

• Description: Discovers .md/configs, proposes, and generates .poml following POML best practices.
• Input (Zod raw shape):
  • mode: "discover" | "plan" | "apply"
  • root?: string (default: repository root)
  • includeGlobs?: string[]
  • excludeGlobs?: string[]
  • selections?: string[] (paths relative to root)
  • outputDir?: string (default poml-output/)
  • stepwise?: boolean (adds <stepwise-instructions>)
  • interpretWindsurf?: boolean (default true, interprets Windsurf workflows)
  • aggregateIndex?: boolean (generates index.poml with <let src=.../>)
  • indexName?: string (default index.poml)
• Output:
  • discovered? (in discover mode)
  • proposals? (in plan mode)
  • wrote?: string[] (in apply mode)

The Markdown template includes: <task>, <output-format>, <cp caption="Style">, and <code><document parser="txt"/></code>. Config files generate a template focused on intent/rules/parameterization.

incident_discovery

• Description: Searches for error signals in the repository and generates a POML triage plan.
• Input:
  • mode?: "discover" | "plan" | "apply" (default discover)
  • root?: string
  • query?: string (to narrow the search)
  • includeGlobs?: string[], excludeGlobs?: string[]
  • errorTerms?: string[], maxFiles?: number
• Output:
  • findings?: { file, hits }[] (discover)
  • poml?: string (plan/apply)

Example (plan):

npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name incident_discovery --tool-arg mode=plan

adk_scaffold_from_poml

• Description: Generates an ADK (Gemini) project skeleton from a POML brief (file path) or inline content. Creates minimal files to bootstrap an agent.
• Input:
  • pomlPath?: string
  • pomlContent?: string
  • outputDir?: string (default adk-agent)
  • agentName?: string (default agent)
  • language?: "python" (currently supported)
  • toolset?: "none" | "github" (adds example tools for issues)
  • force?: boolean (overwrite)
• Output:
  • wrote?: string[]
  • warnings?: string[]
  • notes?: string[]

Example (generate skeleton with GitHub tools):

npx @modelcontextprotocol/inspector --cli node index.mjs \
  --method tools/call --tool-name adk_scaffold_from_poml \
  --tool-arg outputDir=adk-agent --tool-arg toolset=github

windsurf_to_poml (alias)

• Description: Shortcut to poml_translate focused on .windsurf/workflows/*.md.
• Input and Output: identical to poml_translate, with default globs pointing to the .windsurf/workflows/ directory.

generate_docs

• Description: Scans the repository and scaffolds three project docs under an output folder:
  • PLANNING.md — vision, architecture, constraints, stack, tools.
  • TASK.md — active tasks, milestones, debt, discovered during development.
  • AI_RULES.md — global rules for AI IDEs (Windsurf, Gemini CLI, Cursor, Cline, Roo), with reference links.
• Modes: plan (dry-run listing) and apply (write files). Non-destructive by default unless overwrite=true.
• Input:
  • mode?: "plan" | "apply" (default plan)
  • root?: string (default: repository root)
  • outputDir?: string (default docs)
  • planning?: boolean (default true)
  • task?: boolean (default true)
  • rules?: boolean (default true)
  • overwrite?: boolean (default false)
  • ideRules?: ("windsurf"|"gemini"|"cursor"|"cline"|"roo")[]
  • projectName?: string
• Output:
  • proposals? (in plan)
  • wrote?: string[] (in apply)
  • warnings?: string[], notes?: string[]

Examples with Inspector:

npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name generate_docs --tool-arg mode=plan
npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name generate_docs --tool-arg mode=apply --tool-arg outputDir=docs --tool-arg overwrite=true

Gemini CLI tips:

• Add poml in ~/.gemini/settings.json and call the tool from the CLI session.
• Run from the project root so relative paths resolve as expected.

Attribution and Inspiration

• Parts of our global AI IDE rules (docs/AI_RULES.md) and the overall context-engineering approach were inspired by the excellent template by Cole Medin:
  • https://github.com/coleam00/context-engineering-intro
• That repo demonstrates a strong pattern of:
  • Project-wide global rules (CLAUDE.md)
  • An explicit feature brief (INITIAL.md)
  • Generating a Product Requirements Prompt (PRP) and executing it via custom commands.
• POML adapts these ideas for a multi-IDE, MCP-centric workflow. We keep human-first Markdown (PLANNING.md, TASK.md, AI_RULES.md) for IDE compatibility, and provide .poml outputs via poml_translate when agents need structured inputs.

Automated tests (mcp-jest)

Run MCP protocol tests with the CLI and Node API:

npm run test:mcpjest:tools   # CLI: connection, tools, basic execution
npm run test:mcpjest:api     # API: detailed asserts (discover/plan/apply, Windsurf)
npm run test:ci              # Combined suite for CI

API tests validate nested shapes (structuredContent) and write controlled outputs to poml-test-output/.

Conversion of Windsurf Workflows (.windsurf/workflows) to POML

poml_translate detects workflows under .windsurf/workflows/ and, with interpretWindsurf (true by default), applies a specialized POML template that:

• Extracts steps, automation flags (// turbo, // turbo-all), commands, and artifacts.
• Generates clear sections: Title/Summary, Ordered Steps, Flags, Commands, Artifacts, Completion criteria, etc.

Example (included in the repo): .windsurf/workflows/convert-windsurf-to-poml.md.

Apply directly to POML:

npx @modelcontextprotocol/inspector --cli node index.mjs --method tools/call --tool-name poml_translate \
 --tool-arg mode=apply \
 --tool-arg selections=.windsurf/workflows/convert-windsurf-to-poml.md \
 --tool-arg interpretWindsurf=true \
 --tool-arg outputDir=poml-test-output-windsurf \
 --tool-arg aggregateIndex=true

Output: .poml files under poml-test-output-windsurf/ and an index.poml with <let src="..."/> if aggregateIndex is enabled.

CI (GitHub Actions)

Includes an example workflow that runs the combined suite:

name: mcp-tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: .
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: package-lock.json
      - run: npm ci
      - run: npm run test:ci

Environment variables

• DEBUG=1: enables extra logging (decisions, globs, counts, paths). Useful for local diagnostics.
• POML_ENABLE_EXAMPLES=1: exposes poml-example://{name} resources from poml/examples/. Typically disabled in production.
• POML_ROOT: forces a project root different from process.cwd(); by default a heuristic is used (findProjectRoot()).

🧠 Design analysis and decisions

• Stable POML subset (spec/POML_CONVENTIONS.md): minimal tags (<task>, <output-format>, Style/Include/Constraints) for compatibility and predictable DX.
• Zod + MCP SDK: inputSchema/outputSchema as the SDK’s expected “raw” shapes (Zod v3), keeping contracts clear.
• Register before server.connect(): register all capabilities before opening stdio; avoids race conditions.
• Default root (process.cwd() + heuristic): detect .git, .windsurf, package.json to work without prior config.
• Opt-in YAML configuration: poml-mcp.config.yml allows profiles and triggers; deterministic deep-merge with defaults.
• Opt-in example resources: decouples the package from the examples repository in real deployments.
• Windsurf-first: shortcuts for .windsurf/workflows/*.md and windsurf_to_poml alias.

What was extracted (and why):

• spec/POML_CONVENTIONS.md: base convention to avoid conceptual sprawl and enable compatible evolution.
• src/conventions.mjs: centralizes templates and default values (e.g., DEFAULT_OUTPUT_FORMAT, styles, constraints) for consistency.
• Optional POML integration: dynamically loads the JS build if present; avoids hard failures when no bundle is available.
• Root heuristics (findProjectRoot()): supports monorepos and repositories without explicit configuration.
• Windsurf translation: interprets .windsurf/workflows/*.md (honors // turbo / // turbo-all) into executable POML.

See spec/LLM_AUTO_CONFIG_PROMPT.md for the template used by auto_configure.

Registered prompts

poml/enhance

• Guides an LLM to refine the brief and produce POML.

Resources

• poml-example://{name}: lists .poml under poml/examples/.
• gemini-adk://{name}: exposes llms-full.txt (if present at project root). List: llms-full.
• windsurf-workflow://{name}: lists and reads local .windsurf/workflows/*.md.
• poml-generated://{path}: reads POML generated under poml-output/.

MCP Clients

• Transport: stdio (local). SSE/HTTP not included currently.
• Test client: client.mjs.

Publishing to npm (for distribution)

Recommended steps:

1. Define the package name in package.json (e.g., poml-mcp).
2. Remove "private": true and add "files" to publish only what’s needed:
   • "files": ["index.mjs", "client.mjs", "README.md"]
3. Ensure "bin": { "poml-mcp": "index.mjs" } (already present) and "engines": { "node": ">=18" }.
4. npm login (if applicable) and npm publish --access public (for public scopes).
5. In Windsurf, use Option A (npx) with the published name.

Development

• Dependencies: @modelcontextprotocol/sdk@^1.4.0, zod@^3.23.8, fast-glob@^3.3.2.
• Zod/SDK notes:
  • Use “raw” shapes in inputSchema/outputSchema.
  • If you define outputSchema, return structuredContent that validates against the schema.

Roadmap and Backlog

Current status: mcp-jest tests (CLI + API) are green. Windsurf workflow translation to POML is implemented and documented.

Milestone 1 — Windsurf Integration + Packaging

• [ ] Validate connection from Windsurf IDE and verify tools list
• [ ] Provide final mcp_config.json examples for both npx and local (Win/macOS/Linux)
• [x] Prepare npm package metadata: set private=false, ensure files and engines
• [ ] Publish to npm and verify npx execution

Milestone 2 — UX and Discoverability

• [x] windsurf_to_poml tool (alias of poml_translate with interpretWindsurf defaults)
• [x] windsurf-workflow://{name} resource (list .windsurf/workflows/*.md)
• [x] Resource for generated .poml outputs under poml-output/

Milestone 3 — Quality and Testing

• [ ] Snapshot/golden tests for .poml outputs (regression)
• [ ] CI matrix (Ubuntu/Windows/macOS) on Node 18/20/22
• [ ] Lint in CI: markdownlint for README and eslint for code
• [ ] Coverage reporting (optional)

Milestone 4 — Tooling Robustness

• [ ] Improve vendorOf() and heuristics by doc type (mkdocs/sphinx/docusaurus)
• [ ] Specialized POML templates by document type: guide, changelog, ADR, config, etc.
• [ ] Automatic suggestions for includeGlobs/excludeGlobs and detailed warnings
• [ ] Optional logging with DEBUG=1 (decisions, globs, counts, paths)

Milestone 5 — Documentation and Examples

• [ ] Expand .windsurf/workflows/ examples
• [ ] Step-by-step tutorial (end-to-end with Inspector and Windsurf)
• [ ] Changelog and CONTRIBUTING.md

Milestone 6 — Background Orchestrator MCP

• [ ] Implement sibling MCP (background-orchestrator-mcp) with tools: list/start/stop/submit_task/logs/health
• [ ] Local process manager (spawn/PM2) and health probes
• [ ] Optional remote backends (HTTP/queues) with auth
• [ ] Safety: allowlists/tokens; no raw shell exposure by default
• [ ] Docs + examples integrating Gemini CLI and ADK services through MCP

Done

• [x] poml_translate with interpretWindsurf and .windsurf/workflows/ support
• [x] mcp-jest tests (CLI+API) for discover/plan/apply including the Windsurf case
• [x] README updated with tests, CI, and examples

License

MIT