poml-mcp
Version:
MCP server that enhances user prompts using POML-style structure
794 lines (606 loc) • 33.5 kB
Markdown
# 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.
- 
[](https://github.com/iberi22/POML-MCP/actions/workflows/ci.yml)
[](https://microsoft.github.io/poml/latest/)
[](https://github.com/google-gemini/gemini-cli)
[](https://www.npmjs.com/package/poml-mcp)
[](https://www.npmjs.com/package/poml-mcp)
- ✨ 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)](#why-this-mcp-vision-and-goal)
- [Flow Diagram (high-level)](#flow-diagram-high-level)
- [Tools Summary](#tools-summary)
- [YAML Configuration (profiles and triggers)](#yaml-configuration-profiles-and-triggers)
- [LLM Auto-configuration](#llm-auto-configuration)
- [Quick usage (Inspector CLI)](#quick-usage-inspector-cli)
- [POML Integration (optional rendering)](#poml-integration-optional-rendering)
- [Gemini Integration (ADK + Gemini CLI)](#gemini-integration-adk--gemini-cli)
- [Registered tools](#registered-tools)
- [Conversion of Windsurf Workflows (.windsurf/workflows) to POML](#conversion-of-windsurf-workflows-windsurfworkflows-to-poml)
- [CI (GitHub Actions)](#ci-github-actions)
- [Environment variables](#environment-variables)
- [Design analysis and decisions](#design-analysis-and-decisions)
- [Development](#development)
- [Roadmap and Backlog](#roadmap-and-backlog)
- [License](#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)
```mermaid
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
```bash
# 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`:
```json
{
"mcpServers": {
"poml-mcp": {
"command": "npx",
"args": ["-y", "<package-name>"]
}
}
}
```
Short alias for dev:
```json
{
"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`:
```json
{
"mcpServers": {
"poml": {
"command": "npx",
"args": ["-y", "poml-mcp"]
}
}
}
```
### B) Local (development)
At project root:
```bash
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:
```json
{
"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:
```yaml
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:
```bash
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:
```bash
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:
```bash
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)
```mermaid
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:
```yaml
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`:
```json
"poml": {
"command": "npx",
"args": ["-y", "poml-mcp"],
"env": { "POML_ENABLE_EXAMPLES": "1" },
"trust": false
}
```
Local/dev alternative:
```json
"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):
```bash
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):
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```yaml
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