diff --git a/mcp-servers/README.md b/mcp-servers/README.md new file mode 100644 index 0000000..b03e48a --- /dev/null +++ b/mcp-servers/README.md @@ -0,0 +1,62 @@ +# MCP Server Walkthroughs + +> Practical setup guides for MCP servers that pair well with OpenCode. New to MCP itself? Read [`docs/mcp.md`](../docs/mcp.md) first. + +## Featured servers + +| Server | Adds | Type | Walkthrough | +|---|---|---|---| +| **Playwright** | Browser automation — DOM, network, screenshots, accessibility | local | [playwright.md](playwright.md) | +| **Context7** | Live, version-pinned library docs piped into the prompt | remote | [context7.md](context7.md) | +| **Sentry** | Errors, traces, releases | remote (OAuth) | [sentry.md](sentry.md) | +| **Grep by Vercel** | Code search across public GitHub | remote | [grep.md](grep.md) | + +## When to add an MCP server + +- Your AI needs **external state** (browser, DB, ticketing, error tracker) +- You repeatedly run the same external CLI/API from within OpenCode prompts +- You want OpenCode to **act on** a system, not just describe it + +If everything you need is already in local files, you probably don't need MCP yet. + +## Cost of adding a server + +MCP tools land in the model's tool surface every turn. A heavy server (say, a full GitHub integration with 40 tools) can eat 10K+ tokens of context **just to describe the available tools**. Don't add a server you won't use, and disable tools you don't need with the `tools` map: + +```json +{ + "tools": { + "github_*": false, + "slack_*": false + }, + "agent": { + "issue-triager": { + "tools": { + "github_get_issue": true, + "github_list_issues": true + } + } + } +} +``` + +## Discovery + +The [official MCP Registry](https://registry.modelcontextprotocol.io/) lists vetted servers. Search the registry or check the docs for each individual server. + +For new servers, also worth checking: + +- [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) — reference implementations +- The provider's own docs (Sentry, Atlassian, etc. publish their own MCP guides) + +## General troubleshooting + +| Problem | Try | +|---|---| +| Server won't connect | `opencode mcp debug ` | +| OAuth flow stuck | `opencode mcp logout ` then `opencode mcp auth ` | +| Tools missing in the model surface | Check the `tools` map and the agent's `tools` override | +| Local server fails on Windows | Make sure the `command` array uses npx with `-y`, and that Node 18+ is on PATH | +| Timeouts | Bump `timeout` (default 5000ms) under the server's config | + +> 📚 Full MCP guide in OpenCode: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers). diff --git a/mcp-servers/context7.md b/mcp-servers/context7.md new file mode 100644 index 0000000..3602d10 --- /dev/null +++ b/mcp-servers/context7.md @@ -0,0 +1,97 @@ +# Context7 MCP + +> Live, version-pinned library documentation piped into the prompt. Grounds OpenCode's answers in **current** API surfaces — not training-data approximations. + +## Why this matters + +LLMs hallucinate APIs that don't exist or use APIs that were deprecated three versions ago. Context7 fetches real documentation for the libraries you're using at the **version** you're using, and surfaces it to the model. + +## When to reach for it + +- Working with a library you don't know well +- Working with a library that's recently changed (new React versions, framework migrations) +- Debugging "this function should exist but it doesn't" confusion +- Writing code for SDKs/APIs the model's training data doesn't cover well + +## Setup + +Get an API key at [context7.com](https://context7.com). + +Add to `opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" + } + } + } +} +``` + +Set the env var in your shell: + +```bash +export CONTEXT7_API_KEY=ctx7_... +``` + +Restart OpenCode. Verify: + +```bash +opencode mcp list +``` + +## Example prompts + +```text +use context7 to look up the React Router v7 docs for `loader` functions — +specifically how to handle redirects from a loader +``` + +```text +I'm migrating from Next.js 14 to 15. Use context7 to find the breaking +changes in the App Router and surface the ones that affect our project. +``` + +```text +use context7 to check the latest Stripe API for the recommended way to +handle webhook signature verification with raw bodies +``` + +## Resolve before you query + +Context7 resolves a library name + version before fetching docs. Patterns that work: + +```text +context7: resolve "next.js" v15 — then look up streaming rendering +context7: resolve "tailwindcss" v4 — show me the breaking changes from v3 +``` + +You can also just name the library; Context7 will resolve to the latest version it knows. + +## What it covers + +Thousands of libraries — React, Next.js, Vue, Angular, Svelte, Tailwind, TanStack, Prisma, Drizzle, Hono, Fastify, Express, Django, FastAPI, Spring, Rails, etc. — plus most major SaaS SDKs (Stripe, Twilio, Sentry, etc.). + +## What it won't do + +- Cover your **private** code or internal docs (use Memory MCP or a custom internal MCP for that) +- Replace reading the actual codebase (it grounds in *docs*, not your usage) +- Cover obscure libraries with no real documentation + +## Gotchas + +- **API key required** — there's a free tier, but you need to sign up. +- **Token budget** — Context7 returns chunks of docs; very chatty queries can push past your context window. Be specific in what you ask for. +- **Version drift** — pin the version explicitly when your repo's `package.json` is behind latest. + +## Resources + +- [Context7 website](https://context7.com) +- [GitHub: upstash/context7](https://github.com/upstash/context7) +- [List of supported libraries](https://context7.com/libraries) *(check website for current list)* diff --git a/mcp-servers/grep.md b/mcp-servers/grep.md new file mode 100644 index 0000000..3201a25 --- /dev/null +++ b/mcp-servers/grep.md @@ -0,0 +1,93 @@ +# Grep MCP (by Vercel) + +> Code search across public GitHub. Useful for "how do real codebases use X?" research without leaving OpenCode. + +## When to reach for it + +- Researching idiomatic usage of an API or pattern +- Finding examples of a library you're new to +- Comparing implementations across major open-source projects +- Pre-deciding between two patterns by seeing which is more common + +## Setup + +No API key needed for the public endpoint. + +Add to `opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "gh_grep": { + "type": "remote", + "url": "https://mcp.grep.app" + } + } +} +``` + +Restart OpenCode. Verify: + +```bash +opencode mcp list +``` + +## Example prompts + +```text +use gh_grep to search for "useTransition" usage in React 19 codebases. +Find the 3 most common patterns and summarize when each is used. +``` + +```text +search github via gh_grep for examples of "drizzle-orm" with +"transaction" — show me how production codebases structure transactions +``` + +```text +use gh_grep to find how big public Tailwind v4 projects organize their +theme tokens. Pull 3 examples I can browse. +``` + +## What it can do + +- Regex / literal search across public GitHub +- Filter by language, repo, file path +- Return code snippets with surrounding context +- Pagination through large result sets + +## What it won't do + +- Search private repos (only public) +- Replace GitHub's own search for finding *issues* or *PRs* (use the GitHub MCP for those) +- Grade code quality — you'll see code that's wrong as often as code that's right + +## Patterns + +### Compare two patterns + +```text +use gh_grep to count occurrences of `useFormState` vs `useActionState` +in production React codebases (Next.js 15+). Report the ratio and the +top 5 examples for each. +``` + +### Validate an approach + +```text +I'm thinking of using event sourcing for our audit log. Use gh_grep to +find production codebases doing this in TypeScript, and tell me what +patterns they share. Skip the "hello world" projects. +``` + +## Gotchas + +- **Public only** — anything behind a private repo is invisible. +- **Quality varies** — half of GitHub is half-finished side projects. Filter by repo popularity or maintainer when possible. +- **No semantic search** — it's literal/regex, not "code that does X". Be precise in your queries. + +## Resources + +- [grep.app](https://grep.app/) — same backing service, web UI +- [Vercel's announcement](https://vercel.com/blog/) — official Vercel posts about Grep diff --git a/mcp-servers/playwright.md b/mcp-servers/playwright.md new file mode 100644 index 0000000..ca02720 --- /dev/null +++ b/mcp-servers/playwright.md @@ -0,0 +1,98 @@ +# Playwright MCP + +> Drive a real browser from OpenCode — open pages, click elements, fill forms, take screenshots, capture network requests, inspect accessibility trees. + +## When to reach for it + +- Visual iteration: implement a UI, take a screenshot, refine +- E2E test scaffolding +- Reading documentation from sites that aren't well-indexed +- Reproducing a bug a user reported with a URL + +## Setup + +Add to `opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp@latest"], + "enabled": true, + "environment": { + "BROWSER_TYPE": "chromium" + } + } + } +} +``` + +Restart OpenCode. Verify: + +```bash +opencode mcp list +``` + +You should see `playwright` in the list. + +## Example prompts + +```text +use playwright to open https://example.com and screenshot the navbar +``` + +```text +use playwright to visit our staging site at https://staging.example.com, +log in with the credentials in @.dev/staging-creds.json, and +verify the dashboard renders without console errors +``` + +```text +the user reports a bug at https://app.example.com/billing — use playwright to +reproduce: log in, navigate to billing, click "upgrade plan", and report what +happens +``` + +## Visual-iteration loop + +```text +[plan] > here's a mock: [drag mock.png in] + > sketch the HTML/CSS structure that matches +[build] > +[build] > implement it under src/components/Dashboard/ +[build] > use playwright to render the new component at http://localhost:5173/dashboard + > and screenshot it; compare to the mock +[build] > refine until the screenshot matches +``` + +Two-three iteration rounds usually closes the gap. + +## What it can do + +- Open URLs, navigate, fill forms, click, hover, drag +- Take screenshots (full page, viewport, or element-scoped) +- Read DOM (CSS selectors, XPath, ARIA roles) +- Capture network requests/responses +- Inspect console messages +- Run JavaScript in the page context +- Read the accessibility tree + +## What it won't do + +- Persist browser state across sessions by default (use `--user-data-dir` if you need this) +- Bypass strong bot detection (Cloudflare, etc.) +- Replace a real E2E test suite (use the screenshots and traces to *write* the tests) + +## Gotchas + +- **First run is slow** — Playwright downloads a browser the first time you invoke it. +- **Headless by default** — you don't see the browser. Pass `BROWSER_HEADED=1` in `environment` to watch it run (useful for debugging). +- **Cross-origin / authenticated flows** — use Playwright's auth-state file pattern; see the upstream docs. + +## Resources + +- [Source: @playwright/mcp on npm](https://www.npmjs.com/package/@playwright/mcp) +- [Playwright docs](https://playwright.dev/) +- [Visual regression patterns](https://playwright.dev/docs/test-snapshots) diff --git a/mcp-servers/sentry.md b/mcp-servers/sentry.md new file mode 100644 index 0000000..fe8a356 --- /dev/null +++ b/mcp-servers/sentry.md @@ -0,0 +1,98 @@ +# Sentry MCP + +> Pull errors, traces, and releases from your Sentry org into OpenCode. Useful when investigating a production issue or correlating a deploy with new errors. + +## When to reach for it + +- Investigating a production error someone pasted a link to +- Auditing recent errors after a deploy +- Correlating a release with a regression +- Tracking down the request trace for a slow endpoint + +## Setup + +Sentry MCP uses OAuth. OpenCode handles Dynamic Client Registration automatically. + +Add to `opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "sentry": { + "type": "remote", + "url": "https://mcp.sentry.dev/mcp", + "oauth": {} + } + } +} +``` + +Restart OpenCode, then complete OAuth: + +```bash +opencode mcp auth sentry +``` + +A browser will open. Sign in to Sentry and authorize OpenCode. The credentials are stored locally. + +Verify: + +```bash +opencode mcp list # should show "sentry" as authenticated +``` + +## Example prompts + +```text +use sentry to fetch the latest 10 errors in the production environment +``` + +```text +use sentry — pull the error at https://my-org.sentry.io/issues/12345/ +and explain what's happening +``` + +```text +the user got a 500 — request ID is `req_abc123`. find the corresponding +trace in sentry and walk me through what happened +``` + +```text +we deployed `v2.45.0` 30 minutes ago. use sentry to compare error rates +in the last 30 minutes versus the previous hour — any new error types? +``` + +## What it can do + +- List issues / errors with filtering (project, environment, time range, severity) +- Fetch full error context — stack trace, breadcrumbs, request data, user context +- List recent releases and their error counts +- Fetch traces and spans +- Search issues by message or stack frame + +## Common pattern: error → root cause + +```text +use sentry to fetch the most recent occurrence of issue PROJ-12345 +- Look at the stack trace and identify the failing code +- Open the relevant file (use @ syntax) +- Explain the root cause and propose a fix +``` + +## What it won't do + +- Resolve issues automatically (you wouldn't want it to) +- Create new releases or deploys +- Access projects you're not a member of + +## Gotchas + +- **OAuth scope** — the OAuth flow grants the same permissions your Sentry user has. Audit before authorizing on shared/admin accounts. +- **Re-auth periodically** — tokens expire. If queries start failing, run `opencode mcp auth sentry` again. +- **Rate limits** — Sentry's API has rate limits. Heavy querying gets throttled. + +## Resources + +- [Sentry MCP — endpoint and docs](https://mcp.sentry.dev/) +- [Sentry main docs](https://docs.sentry.io/)