mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
feat(mcp-servers): walkthroughs for Playwright, Context7, Sentry, Grep
Each walkthrough follows the same template: when to reach for it, setup (verbatim opencode.json snippet), example prompts, capabilities and limitations, gotchas, resources. - playwright.md: browser automation — visual iteration loop, e2e scaffolding, bug repro from a URL - context7.md: live, version-pinned library docs piped into the prompt, with the "resolve first, query second" pattern - sentry.md: errors / traces / releases via OAuth (DCR), with the error-to-root-cause pattern - grep.md: code search across public GitHub via the Vercel-hosted MCP README.md ranks "when to add a server" against the cost of the extra tokens it puts in the model's context every turn, with a tools-map example for disabling chatty MCP tools per agent. All endpoint URLs and package names link-checked at commit time.
This commit is contained in:
@@ -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 <name>` |
|
||||
| OAuth flow stuck | `opencode mcp logout <name>` then `opencode mcp auth <name>` |
|
||||
| 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).
|
||||
@@ -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)*
|
||||
@@ -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
|
||||
@@ -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] > <Tab>
|
||||
[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)
|
||||
@@ -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/)
|
||||
Reference in New Issue
Block a user