diff --git a/README.md b/README.md index 362d9c5e1..0b68a7544 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ Start with a functional need or User Story, then track it as an issue or ticket before planning. Shipping follows the project's own delivery process. Capture a learning only when it is durable enough to improve the next feature. -> 🍳 **More flows** β†’ bundled recipes: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). +> 🍳 **More flows** β†’ bundled recipes: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). ## 🧩 Plugins @@ -338,7 +338,7 @@ Full catalog β†’ [`CATALOG.md`](docs/CATALOG.md). | | | | --- | --- | -| 🍳 **Recipes** | Bundled how-to sheets: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. | +| 🍳 **Recipes** | Bundled how-to sheets: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. | | πŸ›οΈ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. | | 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. | | πŸ›’ **[Marketplace](docs/MARKETPLACE.md)** | Install scopes and versioning. | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md new file mode 100644 index 000000000..188891b1a --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md @@ -0,0 +1,21 @@ +**Verdict:** READY +**Scope:** Final connect-services recipe against the agreed concise service-setup guide. +**Evidence limits:** Static documentation review; provider authentication and reads were not exercised. Sources checked 2026-10-14. + +## Verified + +- **Choice:** Four options compare use cases, advantages and limits; category tables retain CLI and MCP/native alternatives. +- **Accuracy:** Context savings are conditional, matching [Playwright](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp) and [Claude Code's deferred tools](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). No universal speed or freshness claim remains. +- **Setup:** Commands are labeled examples. The Figma command matches its [official setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). Reusable API access points to Generate Skill. Its cross-skill link uses the source URL so installation does not break it. +- **Verification:** Existing action maps relevant memory, performs target-specific reads and fills the category report without changing services. +- **Checks:** Architecture rules pass; local Markdown links have no broken target; all three bundled recipes validate; diff whitespace check passes. + +## Blockers + +None. + +## Suggestions + +| Finding | Evidence | Minimal improvement | +| --- | --- | --- | +| API and SDK are different layers, though both are useful choices for this guide | [Octokit wraps GitHub APIs](https://github.com/octokit/octokit.js), checked 2026-10-14 | Optionally say β€œAn SDK can wrap an API”; current use-case distinction is sufficient | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md new file mode 100644 index 000000000..34dbdc77b --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md @@ -0,0 +1,49 @@ +# Review: Connect services + +- **Verdict**: approve +- **Diff**: `origin/next...HEAD` plus tracked working edits to the recipe, verification action and report +- **Axes run**: code, functional, relevancy +- **Date**: 2026-10-14 +- **Findings**: 0 critical, 0 warning, 0 minor; formal findings limited to concrete P0/P1 risks + +## Phases + +### Phase 1: Recipe and setup + +- [x] Rename recipe and update its references: `README.md:239`, `token-optimization.md:452`, new `connect-services.md` replaces `mcp-installation.md`. +- [x] Eight actual H4 category headings with emojis: `connect-services.md:49–113`. +- [x] Service tables expose linked CLI, MCP/native and API/SDK alternatives; unsupported Google CLI labeled: `connect-services.md:53–122`. +- [x] Explain memory mapping and link category memory templates: `connect-services.md:5`, `connect-services.md:47–115`. +- [x] Three actionable steps; installation checks existing access, follows documentation, then authenticates; code examples belong to bullets: `connect-services.md:43`, `connect-services.md:125–165`. +- [x] Bold introductory labels use a colon; ordinary bullets avoid unnecessary labels: `connect-services.md:131`, `connect-services.md:138`, `connect-services.md:147`. + +### Phase 2: Verification + +- [x] Public `verify` entry routes to `verify-connection`: `02-project-memory/SKILL.md:4`, `02-project-memory/SKILL.md:14–15`, `02-project-memory/SKILL.md:29`. +- [x] Resolve the local recipe and read it by relative path; relevant memory is not a fixed filename list: `05-verify-connection.md:7`, `05-verify-connection.md:15–17`. +- [x] Simple map, read and report process; rules replace a terminal Test section; unavailable context never means not needed: `05-verify-connection.md:15–26`. +- [x] Read-only operation excludes writes, installs, login, memory changes and secret output; successful reads must match account and target: `05-verify-connection.md:25–26`. +- [x] One category per four-column report; aggregate status preserves failed or unverified required access: `connection-report.md:4–24`. + +### Phase 3: Validator support + +- [x] CLI validation permits H4 subsections only below a direct numbered H3 step; malformed numbered headings still fail; unit cases cover valid subsections, orphans, changed parents and malformed headings: `recipe-validation.ts:397–439`, `recipe-validation.unit.test.ts:120–155`. + +## Findings + +None. + +## Verification + +| Metric | Value | +| --- | --- | +| Verified | 100% (12/12) static acceptance criteria reviewed | +| Files checked | All 10 changed PR files: README, recipe validator, validator unit tests, context CATALOG, project-memory router, verification action, connection report, new connect-services recipe, deleted mcp-installation recipe, token-optimization recipe; three current tracked doc edits included | +| Static check | `git diff --check origin/next` exited 0; scoped README/plugins/CLI search found no old `mcp-installation` reference | +| Unchecked | Provider execution and runtime test results: not-applicable to this read-only static review; provider documentation contents and link availability not independently rechecked | +| Unplanned | None; validator relaxation directly supports requested H4 category structure | +| Completion score | 100: every supplied criterion examined | +| Quality score | 92: criteria statically fulfilled; small duplication and local catalogue resolution indirection remain; runtime/provider behavior is not established by this review | +| Non-blocking simplification | `connect-services.md:9–39`: graph shows a decision sequence, table shows tradeoffs; their functions differ, but graph repeats CLI preference and API fallback. Retaining just the comparison table and a short selection sentence would reduce page length without losing useful choice information | +| Non-blocking clarity | `05-verify-connection.md:15`: local recipe resolution has an existing authoritative location policy at `../../12-cook/references/recipe-locations.md`; linking that policy would remove ambiguity without duplicating it | +| Non-blocking router consistency | `02-project-memory/SKILL.md:36`: β€œreport of what changed” predates the read-only verify entry; scoping it to setup/refresh/rewire would align it with verify's observed-results report | diff --git a/cli/src/contexts/framework/domain/recipes/recipe-validation.ts b/cli/src/contexts/framework/domain/recipes/recipe-validation.ts index 3cff22b1b..879b1515e 100644 --- a/cli/src/contexts/framework/domain/recipes/recipe-validation.ts +++ b/cli/src/contexts/framework/domain/recipes/recipe-validation.ts @@ -394,8 +394,10 @@ function checkSteps( ); const steps: RecipeStep[] = []; const categories: Heading[] = []; + let directStep: RecipeStep | undefined; for (const heading of scopedHeadings) { + if (heading.depth === 3) directStep = undefined; const source = `${"#".repeat(heading.depth)} ${heading.text}`; const match = source.match(STEP_PATTERN); if (match) { @@ -409,7 +411,9 @@ function checkSteps( "Add one meaningful emoji between the step number and title." ); } - steps.push({ ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] }); + const step = { ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] }; + steps.push(step); + if (heading.depth === 3) directStep = step; continue; } @@ -423,13 +427,13 @@ function checkSteps( ); } else if (heading.depth === 3) { categories.push(heading); - } else { + } else if (!directStep) { addFinding( findings, file, heading.line, "category-depth", - "Use level 3 for a category and level 4 only for its numbered steps." + "Use level 4 for numbered category steps or subsections of a direct numbered step." ); } } diff --git a/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts b/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts index d2c52df9a..41c152679 100644 --- a/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts +++ b/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts @@ -104,7 +104,7 @@ test("categories require level-four steps and cannot parent earlier steps", () = recipe(command, "### Beginner\n\n#### Unnumbered step"), "category-depth", 9, - "Use level 3 for a category and level 4 only for its numbered steps." + "Use level 4 for numbered category steps or subsections of a direct numbered step." ); }); @@ -117,6 +117,41 @@ test("direct steps stay at level three", () => { ); }); +test("direct numbered steps allow unnumbered level-four subsections", () => { + const content = recipe( + `#### Version control\n\n${command}\n\n#### Database\n\n${command}\n\n### 2) πŸ”Œ Connect\n\n#### Authentication\n\n${command}` + ); + assert.deepEqual(inspectRecipe(file, content).findings, []); +}); + +test("unnumbered level-four subsections require a direct numbered parent", () => { + for (const heading of [ + "#### Orphan subsection", + "### 1. βœ… Check readiness\n\n#### Subsection", + "### 1) βœ… Check readiness\n\n### Beginner\n\n#### Subsection", + "### Beginner\n\n#### 1) βœ… Check readiness\n\n#### Subsection", + ]) { + assert.equal( + inspectRecipe(file, recipe(command, heading)).findings.some( + (item) => item.rule === "category-depth" + ), + true + ); + } +}); + +test.each(["#### 2. πŸ”Œ Connect", "#### 2 πŸ”Œ Connect"])( + "subsections do not hide malformed numbered step heading %s", + (heading) => { + finding( + recipe(`${heading}\n\n${command}`), + "step-heading", + 9, + "Use `### N) Title`, or `#### N) Title` below a category." + ); + } +); + test("step numbering continues across categories instead of restarting", () => { const content = recipe( `${command}\n\n### Advanced\n\n#### 1) πŸ”¬ Inspect output\n\n${command}`, diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 06c1317db..f2d036ae5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -75,6 +75,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write.md](skills/02-project-memory/actions/02-write.md) | - | | `actions` | [03-check.md](skills/02-project-memory/actions/03-check.md) | - | | `actions` | [04-sync.md](skills/02-project-memory/actions/04-sync.md) | - | +| `actions` | [05-verify-connection.md](skills/02-project-memory/actions/05-verify-connection.md) | - | +| `assets` | [connection-report.md](skills/02-project-memory/assets/connection-report.md) | - | | `assets` | [report.md](skills/02-project-memory/assets/report.md) | - | | `assets` | [scan-summary.md](skills/02-project-memory/assets/scan-summary.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | @@ -85,7 +87,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [review-protocol.md](skills/02-project-memory/references/review-protocol.md) | - | | `references` | [structure.md](skills/02-project-memory/references/structure.md) | - | | `references` | [tools.md](skills/02-project-memory/references/tools.md) | - | -| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file.` | +| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file.` | #### `skills/03-context-generate` diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index e854cb94b..f031faf5a 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -1,7 +1,7 @@ --- name: 02-project-memory -description: Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file. -argument-hint: setup | refresh | rewire +description: Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file. +argument-hint: setup | refresh | rewire | verify --- # Project Memory @@ -11,6 +11,8 @@ flowchart LR new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired]) update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync + verify([verify]) --> verify-connection + verify-connection --> reported([connection report]) scan -.-> empty([nothing to remember]) ``` @@ -24,10 +26,11 @@ Run the flow above, reading only the next action file. | write | write the memory | | check | show what drifted, change nothing | | sync | pick the tools, wire it in | +| verify-connection | verify the assistant's service access | ## Transversal rules -- If a referenced file cannot be read, stop and say so. Never invent its content. +- Never invent unreadable content; setup, refresh and rewire stop when a referenced file cannot be read. - Ask before anything ambiguous. Never default silently. - A bank that already exists changes only through what the user approved, file by file and line by line. - End with a short report of what changed. diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md new file mode 100644 index 000000000..b4eeee682 --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -0,0 +1,26 @@ +# 05 - Verify Connection + +Check project access and fill the report. + +## Input + +The project's bank in `aidd_docs/memory/` and the local `connect-services.md` recipe. + +## Output + +A printed report using [connection-report.md](../assets/connection-report.md). + +## Process + +1. **Map**: Resolve `connect-services.md` from the local recipe catalogue, then read it by its relative path and read the relevant project memory to identify required services, accounts and targets. + - Include any other relevant memory files or services. + - Mark missing context as unverified, never as not needed. +2. **Check**: Inspect available CLI, MCP, native or API access and perform one read against each required account and target. + - Continue checking the other services when one fails. +3. **Report**: Fill `connection-report.md` from observed results, with one row per category. + +## Rules + +- Check the assistant access the project requires; the catalogue is not an installation checklist. +- No writes, installs, login flows, configuration or memory changes, or secret output. +- A configured tool alone never proves access; report success only after a read matches the intended account and target. diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md new file mode 100644 index 000000000..a19b75744 --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -0,0 +1,24 @@ +# Connection Report + + + +| Category | Tool / target | Status | Evidence / next step | +| --- | --- | --- | --- | +| Version control | | | | +| Ticketing | | | | +| Documentation and workspace | | | | +| Browser | | | | +| Design | | | | +| Monitoring | | | | +| Deployment | | | | +| Database | | | | + +βœ… All required reads passed Β· ❌ Read failed Β· πŸ”Œ Not configured Β· ⚠️ Unverified Β· ⏭️ Not needed diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md new file mode 100644 index 000000000..50066b5be --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -0,0 +1,147 @@ +# Connect your services + +Connect CLI, MCP, API or SDK access so your AI assistant can work with your team's services. + +**Each category points to the project memory that records how your team uses those services.** + +> This gives the assistant the right repository, workspace and conventions for its work. + +## CLI, MCP, API or SDK? + +Reuse an existing connection that covers your task. Prefer CLI when it covers the task and follows official recommendations. + +| πŸ”Œ Option | 🎯 When to use it | βœ… Advantages | ⚠️ Limits | +| --- | --- | --- | --- | +| CLI | Repeatable tasks with shell access | Scriptable; filter output; can reduce context overhead | Commands vary by version; check installed `--help`; coverage may be incomplete | +| MCP | Direct assistant interaction | Structured inputs; discoverable tools; simple invocation | Client compatibility; tool and output context cost; [server trust and permissions](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) | +| [API](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api) | Operations missing from existing tools | Control requests, filters and returned data | Handle authentication, pagination, rate limits and errors | +| [SDK](https://github.com/octokit/octokit.js) | Reusable integrations in code | Language-native calls; less request boilerplate | Dependencies and version compatibility; coverage varies by library | + +[Playwright documents lower CLI context use](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp); [Claude Code can load MCP tools on demand](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). Speed and token cost depend on the tool and client. + +## Steps to connect your services + +### 1) πŸ”Ž Choose the tool + +For each service your project uses, choose an option that covers your task. Add another only for a need the first cannot cover. + +Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. + +#### πŸ”€ Version control + +> Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | +| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | + +#### 🎫 Ticketing + +> Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | + +#### πŸ“š Documentation and workspace + +> Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | +| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | + +#### 🌐 Browser + +> Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | +| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | +| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | + +#### 🎨 Design + +> Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | + +#### 🚨 Monitoring + +> Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | + +#### πŸš€ Deployment + +> Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | + +#### πŸ—„οΈ Database + +> Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). + +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | +| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | +| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | + +Add any other services your team uses to the relevant table. `β€”` means no option is listed here. + +### 2) πŸ”Œ Install and sign in + +1. Check existing access; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), `/mcp` shows MCP server status. +2. Follow the linked guide for your chosen option and client; install only what is missing. +3. Review the account, workspace and requested permissions, then authenticate; use read-only access when you only need reads. + +These are setup examples, not required installations. Follow the guide for your service and client. + +- **CLI / GitHub**: Install `gh` from its [guide](https://github.com/cli/cli#installation), then sign in and inspect the account: + + ```bash + gh auth login + gh auth status + ``` + +- **MCP / Figma in Claude Code**: Install the recommended plugin: + + ```bash + claude plugin install figma@claude-plugins-official + ``` + + Start a new session, run `/mcp`, select Figma, then **Authenticate**; other clients use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). + +- **API / GitHub**: Wrap reusable API access in a skill with `/aidd-context:04-skill-generate` ([Generate Skill](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/04-skill-generate/SKILL.md)). With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: + + ```bash + curl --fail --silent --show-error \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + https://api.github.com/user + ``` + +Require confirmation for writes; if your client cannot enforce it, disable write tools or use provider-enforced read-only access. + +### 3) βœ… Check the connection + +Ask your assistant to verify project access using the [verification action](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md) and its [report table](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md): + +- Run this prompt after recording the services and targets in project memory: + + ```text + Verify this project's connections against aidd_docs/memory/. + ``` diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md deleted file mode 100644 index 67b564bee..000000000 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ /dev/null @@ -1,156 +0,0 @@ -# MCP installations - -Choose between a CLI and MCP by capability, then install the integration through the configuration native to your AI client. - - - -## Steps to install the right integration - -### 1) πŸ”Ž Choose by capability - -Choose the smallest interface that fully covers the workflow, authentication model, and data scope. - -1. Compare the exact operation you need against the table. - -| Need | Prefer a CLI | Prefer MCP | -| --- | --- | --- | -| Scriptable commands and raw API calls | The official CLI covers the operation and its output is manageable | The client needs typed discovery or structured results | -| Live design or knowledge context | The CLI exposes the required operation and data | The server advertises the required tools, resources, or prompts | -| Authentication | The CLI's login and credential storage fit the workflow | The server's authentication, requested scopes, and host credential storage fit the workflow | -| Context cost | Output is requested only when the command runs | The client supports deferred loading such as [Claude Code Tool Search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) | - -The last column is a decision heuristic for this recipe, not a provider guarantee. - -β€œOfficial” means published by the service provider, not a guarantee of production readiness or contractual support. Statuses below were checked against the linked provider sources on 2026-10-13. β€œNot listed” means this recipe does not identify an official option. - -| Usage | Service | MCP offered and status | CLI alternative and status | Recommended | -| --- | --- | --- | --- | --- | -| **Version control**: Manage issues, PRs, releases, and CI runs | **GitHub** | **Official**: [`api.githubcopilot.com/mcp/`](https://github.com/github/github-mcp-server) | **Official**: [`gh`](https://cli.github.com/manual/) | **CLI** | -| - | **GitLab** | **Official, experimental**: [`glab mcp serve`](https://docs.gitlab.com/cli/mcp/) | **Official**: [`glab`](https://docs.gitlab.com/cli/) | **CLI** | -| **Ticketing**: Search, create, and update tickets | **Jira** | **Official**: [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | **Official**: [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) | **CLI** | -| - | **Linear** | **Official**: [`mcp.linear.app/mcp`](https://linear.app/docs/mcp) | Not listed | **MCP** | -| **Internal Doc**: Search and maintain team documentation | **Confluence** | **Official**: [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | Not listed | **MCP** | -| - | **Notion** | **Official**: [`mcp.notion.com/mcp`](https://developers.notion.com/guides/mcp/get-started-with-mcp) | **Official**: [`ntn`](https://developers.notion.com/cli/get-started/overview) for API and page operations | **CLI** for scripts and API work; **MCP** for agent workflows | -| **Workspace**: Work with Drive, Docs, Sheets, Gmail, and Calendar | **Google Workspace** | Not listed | [`gws`](https://github.com/googleworkspace/cli): published under `googleworkspace`, but **not officially supported by Google** | **CLI**, if its support status meets the project's requirements | -| **Browsing**: Test user journeys and inspect browser behavior | **Playwright** | **Official**: [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | **Official**: [`playwright-cli`](https://playwright.dev/agent-cli/installation) for browser automation; [`npx playwright`](https://playwright.dev/docs/test-cli) for tests | **CLI** for direct browser automation and tests; **MCP** for live tool calls | -| **UI**: Read design context to implement an interface | **Figma** | **Official**: [`mcp.figma.com/mcp`](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | **Official**: [`@figma/code-connect`](https://developers.figma.com/docs/code-connect/cli-reference/) for component mappings, not live design context | **CLI** for Code Connect mappings; **MCP** for live design context | -| **Monitoring**: Inspect errors and investigate incidents | **Sentry** | **Official**: [`mcp.sentry.dev/mcp`](https://github.com/getsentry/toolkit) | **Official**: [`sentry`](https://cli.sentry.dev/) for issue investigation; [`sentry-cli`](https://github.com/getsentry/sentry-cli) for releases and source maps | **CLI** when it covers the investigation; **MCP** for interactive debugging | -| **Deployment**: Deploy applications and inspect deployment logs | **Vercel** | **Official**: [`mcp.vercel.com`](https://vercel.com/docs/agent-resources/vercel-mcp) | **Official**: [`vercel`](https://vercel.com/docs/cli) | **CLI** for repeatable deployment workflows; **MCP** for interactive exploration | -| **Database**: Manage migrations, develop locally, and explore a project | **Supabase** | **Official**: [`mcp.supabase.com/mcp`](https://supabase.com/docs/guides/ai-tools/mcp) | **Official**: [`supabase`](https://supabase.com/docs/reference/cli/introduction) | **CLI** for migrations and local development; **MCP** for interactive exploration | - -### 2) ⌨️ Install the CLI route - -The agent-oriented Playwright CLI is a direct browser alternative to Playwright MCP. - -1. Install `@playwright/cli` from the [official guide](https://playwright.dev/agent-cli/installation), then invoke its `playwright-cli` executable. - -```bash -npm install -g @playwright/cli@latest -playwright-cli open https://example.com --headed -``` - -Optional rollback: `npm uninstall -g @playwright/cli`. - -Use `npx playwright test` for the test runner and `npx playwright codegen` for test generation; they are different command surfaces. - -### 3) πŸ”Œ Install the MCP route - -Use a provider-supported client and distinguish the recommended plugin route from manual MCP configuration. - -1. Pick the [documented Figma route](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) for your client. - -| Client | Figma's recommended route | Manual alternative and scope | -| --- | --- | --- | -| Claude Code | `claude plugin install figma@claude-plugins-official` | `claude mcp add --transport http --scope project figma https://mcp.figma.com/mcp` writes project configuration to `.mcp.json` under `mcpServers` | -| Codex | In the Codex app, open **Plugins**, select **+** next to Figma, then **Install Figma** | `codex mcp add figma --url https://mcp.figma.com/mcp` writes to [`~/.codex/config.toml`](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) under `mcp_servers`; trusted projects may instead use `.codex/config.toml` | -| Cursor | Run `/add-plugin figma` | Manual project configuration uses `.cursor/mcp.json` under `mcpServers` | -| GitHub Copilot in VS Code | Run **MCP: Open Workspace Folder MCP Configuration**, paste Figma's documented server object, then select **Start** | Workspace configuration uses `.vscode/mcp.json` under `servers` | - -```bash -claude plugin install figma@claude-plugins-official -``` - -[Figma accepts only clients in its MCP catalog](https://www.figma.com/mcp-catalog/); do not extrapolate these instructions to an unlisted host. - -### 4) πŸ” Restrict access - -Use the server's documented authentication, expose only required capabilities, and enforce confirmation for mutations. - -1. If the remote server uses OAuth, authorize it in the client and review the requested scopes; otherwise follow its documented authentication method. -2. Prefer read-only endpoints, toolsets, or allowlists when the workflow only reads. -3. Configure the host to require confirmation for mutating tools; if it cannot, disable write tools or use a provider-enforced read-only mode. - -[GitHub documents](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md#read-only-mode) this VS Code-format server-entry fragment; place it under `servers.github` in `.vscode/mcp.json`, or adapt the wrapper to the selected host: - -```json -{ - "type": "http", - "url": "https://api.githubcopilot.com/mcp/", - "headers": { - "X-MCP-Toolsets": "repos,issues", - "X-MCP-Readonly": "true" - } -} -``` - -[Notion MCP inherits the connected user's workspace access](https://developers.notion.com/guides/mcp/mcp-security-best-practices), so review every write and any data sent to another tool. - -### 5) βœ… Verify the connection - -Verify the configured server, authenticated identity, exposed tools, and one read-only operation before relying on it. - -1. Inspect the server through the client, then run a harmless read. - -```text -Claude Code: /mcp -Codex: codex mcp list -Cursor: Settings > Cursor Settings > Tools & MCP -VS Code: MCP: List Servers -``` - -Figma's documented successful Claude Code flow ends with: - -```text -Authentication successful. Connected to figma -``` - -Use Figma's read-only [`whoami`](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/#whoami-remote-only) tool to confirm the authenticated email, plans, and seat type. - -### 6) 🧹 Optional rollback: remove local access - -Clearing authentication and local configuration stops the client from using the server. - -1. Clear authentication before removing the server entry. -2. Remove the server or plugin from the client. - -| Client | Clear authentication | Remove local configuration | -| --- | --- | --- | -| Claude Code | Run `/mcp`, select Figma, then **Clear authentication** | Plugin: `claude plugin uninstall figma@claude-plugins-official`; manual project server: `claude mcp remove --scope project figma` | -| Codex | Manual server: `codex mcp logout figma` | Plugin: remove Figma in the Codex app's **Plugins** panel; manual server: `codex mcp remove figma` | -| Cursor | Disconnect Figma under **Settings > Cursor Settings > Tools & MCP** | Remove the Figma plugin or its manual `.cursor/mcp.json` entry | -| GitHub Copilot in VS Code | Select the server through **MCP: List Servers** | Uninstall the server or remove its `.vscode/mcp.json` entry | - -```bash -codex mcp logout figma -codex mcp remove figma -``` - -Removing configuration alone does not prove that the OAuth grant was revoked. - -### 7) 🚫 Optional teardown: revoke provider access - -Revoking the provider grant invalidates the remote OAuth authorization independently of local configuration. - -1. For Figma, open [**Settings > Security > Connected apps**](https://help.figma.com/hc/en-us/articles/15021280611607-How-do-I-keep-my-account-secure). -2. Find the MCP client and select **Revoke access**. - -```text -Figma > Settings > Security > Connected apps > Revoke access -``` - -## Verify - -- The server appears in the chosen client's server list with the expected transport and scope. -- Authentication uses the intended account and workspace; for Figma, `whoami` returns that identity. -- Only the required tools are enabled; mutating calls require confirmation or are disabled. -- For optional rollback or teardown, check authentication clearing, local removal, and provider revocation separately. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md index 1449a3466..3bd67e561 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md @@ -449,7 +449,7 @@ enabled = false Set `enabled = true` or remove the override to restore the server. -See [Claude Code MCP](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), and [`mcp-installation.md`](mcp-installation.md). +See [Claude Code MCP](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), and [`connect-services.md`](connect-services.md). ### πŸ”΄ Expert