vikingowl
6a94373c4f
- Replace brand-specific guidance with spec-compliant naming rules and connector categories. - Add docs/mcp-reference.md outlining common MCP connectors and installation workflow. - Point configuration docs at the new guide and reiterate the naming regex. Acceptance Criteria: - Documentation directs users toward a combined reference bundle without citing specific vendors. Test Notes: - Docs-only change; link checks not run.
42 lines
4.6 KiB
Markdown
42 lines
4.6 KiB
Markdown
# MCP Reference Bundles
|
||
|
||
Owlen’s MCP configuration guidance now targets the same canonical toolset shipped by leading desktop and IDE clients, without relying on brand-specific heuristics. This document distills the common naming rules, connector categories, and installation patterns you should follow when wiring those tools into Owlen.
|
||
|
||
## Naming Rules
|
||
|
||
- Tool identifiers must match the regular expression `^[A-Za-z0-9_-]{1,64}$`.citeturn11search0
|
||
- Avoid dots or spaces in identifiers; use underscores when you need multiword names (`sequential_thinking`, `browser_fetch`).
|
||
- When multiple servers expose similarly named tools, qualify the call using `{server}__{tool}` (for example, `filesystem__read` or `browser__request`).
|
||
|
||
## Connector Categories
|
||
|
||
| Category | Connector | Capability Highlights | Typical Command Snippet |
|
||
| --- | --- | --- | --- |
|
||
| Core context | `filesystem` | Mount local directories for read/write access during a chat session.citeturn1search6 | `npx -y @modelcontextprotocol/server-filesystem <paths…>` |
|
||
| Core context | `sequential-thinking` | Structured problem solving with persistent reasoning chains and Memory Bank integration.citeturn1search0turn1search6 | `npx -y @modelcontextprotocol/server-sequential-thinking` |
|
||
| Core context | `fetch` | Lightweight HTTP client for REST/JSON retrieval.citeturn1search6 | `npx -y @kazuph/mcp-fetch` |
|
||
| Automation | `puppeteer` | Headless browser automation (navigation, screenshots, DOM scripting).citeturn1search5turn1search7 | `npx -y @modelcontextprotocol/server-puppeteer` |
|
||
| Automation | `browser-tools` / `devtools` | Deep Chrome DevTools integration for inspection and profiling.citeturn1search6 | `npx -y @modelcontextprotocol/server-browser-tools` |
|
||
| Retrieval | `brave-search`, `firecrawl` | API-driven web search and scraping for current information (requires API keys).citeturn1search6turn1search8 | `claude mcp add brave-search …` (replace with `owlen mcp add brave_search …`) |
|
||
| Retrieval | `perplexity`, `tavily`, `search1api` | Aggregated search/QA endpoints with structured responses.citeturn1search8 | `owlen mcp add tavily -- npx -y @tavily/mcp-server` |
|
||
| Observability | `sentry`, `raygun` | Incident and crash analytics access for production systems.citeturn1search8 | `owlen mcp add sentry -- npx -y @sentry/mcp-server` |
|
||
| Productivity | `notion`, `slack`, `stripe`, `zapier`, `google_drive` | Common SaaS integrations for knowledge bases, messaging, payments, automation, and storage.citeturn1search8 | `owlen mcp add notion -- npx -y @notion/mcp-server` |
|
||
| Data | `postgresql`, `sqlite`, `qdrant`, `redis`, `tinybird` | Database and vector-store connectors for analytics and retrieval.citeturn1search8 | `owlen mcp add postgresql -- npx -y @modelcontextprotocol/server-postgresql` |
|
||
| Execution | `python`, `notebook`, `riza`, `semgrep` | Sandbox code execution, notebook orchestration, security linting.citeturn1search8 | `owlen mcp add python -- npx -y @modelcontextprotocol/server-python` |
|
||
|
||
> **Tip:** Replace any vendor-specific CLI (for example, `claude mcp add`) with the upcoming `owlen mcp add` command when working within Owlen. Until that lands, copy the arguments into `config.toml` directly or wrap them in project scripts—the syntax is intentionally mirrored so the migration is mechanical.
|
||
|
||
## Installation Workflow
|
||
|
||
1. **Plan your bundle.** Start with the core context servers (`filesystem`, `sequential-thinking`, `fetch`, `puppeteer`). Layer in retrieval, observability, productivity, and execution connectors as your project requires.
|
||
2. **Add each server under `[mcp_servers]`.** Use spec-compliant names and consider grouping them by category inside `config.toml`.
|
||
3. **Qualify tool calls.** When writing prompts or unit tests, address tools using `{server}__{tool}` to avoid collisions once you enable multiple servers that expose similar endpoints.
|
||
4. **Document required secrets.** Many SaaS connectors need API keys. Store their environment variables in your preferred secret manager and reference them in the `[mcp_servers.<name>.env]` table.
|
||
5. **Run health checks.** Each connector listed above includes a health or status endpoint; wire these into your startup scripts so Owlen can surface actionable errors before a chat begins.
|
||
|
||
## Next Steps
|
||
|
||
- Update `config.toml` with the reference bundle (see `docs/configuration.md`).
|
||
- Use `owlen tools audit` to remove or disable any legacy MCP servers that do not meet the naming constraints.
|
||
- Track connector-specific onboarding (API keys, OAuth scopes) in team documentation so new contributors can reproduce the setup quickly.
|