diff --git a/docs.json b/docs.json index 9a409619..e07f2f3e 100644 --- a/docs.json +++ b/docs.json @@ -40,7 +40,7 @@ "tab": "Auth", "groups": [ { - "group": "Overview", + "group": "Getting Started", "pages": [ "index", "overview/pricing", @@ -171,6 +171,85 @@ } ] } + }, { + "tab": "Nexus", + "groups": [ + { + "group": "Getting Started", + "icon": "rocket", + "pages": [ + "nexus/overview", + "nexus/quickstart/index", + "nexus/concepts/toolkits", + "nexus/reference/authorizations" + ] + }, + { + "group": "Supported Clients", + "icon": "desktop", + "pages": [ + "nexus/quickstart/nexus-chat", + "nexus/quickstart/clients/mistral-lechat", + "nexus/quickstart/clients/claude-web", + "nexus/quickstart/clients/claude-desktop", + { + "group": "More Clients", + "icon": "ellipsis", + "pages": [ + "nexus/quickstart/clients/cursor", + "nexus/quickstart/clients/goose", + "nexus/quickstart/clients/vscode", + "nexus/quickstart/clients/windsurf", + "nexus/quickstart/clients/claude-code", + "nexus/quickstart/clients/jetbrains", + "nexus/quickstart/clients/gemini" + ] + }, + { + "group": "MCP Servers", + "icon": "server", + "pages": [ + "nexus/reference/servers", + "nexus/reference/servers/activecampaign", + "nexus/reference/servers/github", + "nexus/reference/servers/slack", + "nexus/reference/servers/notion", + "nexus/reference/servers/n8n", + "nexus/reference/servers/postgresql", + "nexus/reference/servers/sentry", + "nexus/reference/servers/linear", + "nexus/reference/servers/hubspot", + "nexus/reference/servers/dropbox", + "nexus/reference/servers/coingecko" + ] + } + ] + }, + { + "group": "Developers", + "icon": "code", + "pages": [ + "nexus/developers/client-setup", + "nexus/developers/vercel-ai-sdk", + "nexus/quickstart/hub-bridge" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "nexus/reference/client-compatibility", + "nexus/reference/security" + ] + }, + { + "group": "Support", + "icon": "life-buoy", + "pages": [ + "nexus/troubleshooting" + ] + } + ] },{ "tab": "Labs", "groups": [ diff --git a/images/steps/claude/01.png b/images/steps/claude/01.png new file mode 100644 index 00000000..cbd765e8 Binary files /dev/null and b/images/steps/claude/01.png differ diff --git a/images/steps/claude/02.png b/images/steps/claude/02.png new file mode 100644 index 00000000..6e81ff04 Binary files /dev/null and b/images/steps/claude/02.png differ diff --git a/images/steps/claude/03.png b/images/steps/claude/03.png new file mode 100644 index 00000000..3a5d64d6 Binary files /dev/null and b/images/steps/claude/03.png differ diff --git a/images/steps/claude/04.png b/images/steps/claude/04.png new file mode 100644 index 00000000..c347e9f0 Binary files /dev/null and b/images/steps/claude/04.png differ diff --git a/images/steps/claude/05.png b/images/steps/claude/05.png new file mode 100644 index 00000000..17137a2c Binary files /dev/null and b/images/steps/claude/05.png differ diff --git a/images/steps/mistral/01.png b/images/steps/mistral/01.png new file mode 100644 index 00000000..fd8fb210 Binary files /dev/null and b/images/steps/mistral/01.png differ diff --git a/images/steps/mistral/02.png b/images/steps/mistral/02.png new file mode 100644 index 00000000..bc4738ed Binary files /dev/null and b/images/steps/mistral/02.png differ diff --git a/images/steps/mistral/03.png b/images/steps/mistral/03.png new file mode 100644 index 00000000..e7b9534f Binary files /dev/null and b/images/steps/mistral/03.png differ diff --git a/images/steps/mistral/04.png b/images/steps/mistral/04.png new file mode 100644 index 00000000..c2f8816b Binary files /dev/null and b/images/steps/mistral/04.png differ diff --git a/images/steps/mistral/05.png b/images/steps/mistral/05.png new file mode 100644 index 00000000..e7b9534f Binary files /dev/null and b/images/steps/mistral/05.png differ diff --git a/images/steps/mistral/06.png b/images/steps/mistral/06.png new file mode 100644 index 00000000..42454642 Binary files /dev/null and b/images/steps/mistral/06.png differ diff --git a/images/steps/security/01.png b/images/steps/security/01.png new file mode 100644 index 00000000..42975288 Binary files /dev/null and b/images/steps/security/01.png differ diff --git a/images/steps/toolkit/01.png b/images/steps/toolkit/01.png new file mode 100644 index 00000000..e6e373a3 Binary files /dev/null and b/images/steps/toolkit/01.png differ diff --git a/images/steps/toolkit/02.png b/images/steps/toolkit/02.png new file mode 100644 index 00000000..c313596f Binary files /dev/null and b/images/steps/toolkit/02.png differ diff --git a/images/steps/toolkit/03.png b/images/steps/toolkit/03.png new file mode 100644 index 00000000..725c5bb7 Binary files /dev/null and b/images/steps/toolkit/03.png differ diff --git a/images/steps/toolkit/overview.png b/images/steps/toolkit/overview.png new file mode 100644 index 00000000..8d79239a Binary files /dev/null and b/images/steps/toolkit/overview.png differ diff --git a/images/steps/welcome/01.png b/images/steps/welcome/01.png new file mode 100644 index 00000000..b49b3b4a Binary files /dev/null and b/images/steps/welcome/01.png differ diff --git a/images/steps/welcome/02.png b/images/steps/welcome/02.png new file mode 100644 index 00000000..551e300e Binary files /dev/null and b/images/steps/welcome/02.png differ diff --git a/images/steps/welcome/03.png b/images/steps/welcome/03.png new file mode 100644 index 00000000..b49b3b4a Binary files /dev/null and b/images/steps/welcome/03.png differ diff --git a/images/steps/welcome/04.png b/images/steps/welcome/04.png new file mode 100644 index 00000000..2b3a130b Binary files /dev/null and b/images/steps/welcome/04.png differ diff --git a/images/steps/welcome/05.png b/images/steps/welcome/05.png new file mode 100644 index 00000000..0fdd2441 Binary files /dev/null and b/images/steps/welcome/05.png differ diff --git a/images/steps/welcome/06.png b/images/steps/welcome/06.png new file mode 100644 index 00000000..1be54a5f Binary files /dev/null and b/images/steps/welcome/06.png differ diff --git a/integration/mobile/react-native.mdx b/integration/mobile/react-native.mdx index 8edd26d4..f7c06fdb 100644 --- a/integration/mobile/react-native.mdx +++ b/integration/mobile/react-native.mdx @@ -13,7 +13,7 @@ React Native applications can integrate with Civic Auth using any OAuth2/OIDC-co - [**Expo AuthSession**](https://docs.expo.dev/versions/latest/sdk/auth-session/) - [**react-native-app-auth**](https://github.com/FormidableLabs/react-native-app-auth) -For a complete OAuth2/OIDC integration details, see the [Civic Auth Integration Guide](https://docs.civic.com/auth/integration/other). +For a complete OAuth2/OIDC integration details, see the [Civic Auth Integration Guide](/integration/other). ## Reference Implementation @@ -76,5 +76,5 @@ const authContext = { ## Resources -- [Civic Auth OAuth2/OIDC Integration](https://docs.civic.com/auth/integration/other) +- [Civic Auth OAuth2/OIDC Integration](/integration/other) - [Complete React Native Example](https://github.com/civicteam/civic-auth-examples/tree/main/packages/mobile/react-native-expo) diff --git a/labs/private/mcp-hub.mdx b/labs/private/mcp-hub.mdx index f7bbe00a..08ae5dc8 100644 --- a/labs/private/mcp-hub.mdx +++ b/labs/private/mcp-hub.mdx @@ -102,30 +102,45 @@ Use the MCP Hub with Vercel AI SDK for building AI applications. ```typescript import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { getTokens } from "@civic/auth/nextjs"; -// Get access token -const { accessToken } = await getTokens() - -// Create MCP client const createMCPClient = async () => { + // Get access token + const { accessToken } = await getTokens(); + + if (!accessToken) { + throw new Error('No access token available. User needs to authenticate.'); + } + + // Create transport with authentication const transport = new StreamableHTTPClientTransport( 'https://nexus.civic.com/hub/mcp', { requestInit: { headers: { - Authorization: `Bearer ${accessToken}` + Authorization: `Bearer ${accessToken}`, + 'Content-Type': 'application/json' } } } ); - return createMCPClient({ - transport + // Initialize MCP client + const client = new Client({ + name: 'my-app', + version: '1.0.0' + }, { + capabilities: {} }); + + await client.connect(transport); + return client; }; ``` +For complete Vercel AI SDK integration examples, see our [detailed Vercel AI SDK guide](/nexus/developers/vercel-ai-sdk). + ### 3. n8n Workflow Integration Build AI-powered workflows with n8n and Civic Labs. diff --git a/nexus/concepts/connection-methods.mdx b/nexus/concepts/connection-methods.mdx new file mode 100644 index 00000000..a02adcbe --- /dev/null +++ b/nexus/concepts/connection-methods.mdx @@ -0,0 +1,163 @@ +--- +title: Connection Methods +description: Remote URL vs Hub Bridge - understanding how your AI connects to Nexus +icon: "network-wired" +--- + +## Two Ways to Connect + +There are two ways your AI client can connect to Nexus servers. The method depends on what your AI client supports: + +## Remote URL Method + +**Simple copy/paste connection** for clients that support remote MCP servers. + +### How it works: +1. Visit nexus.civic.com and select your tools +2. Copy the MCP URL: `https://nexus.civic.com/hub/mcp` +3. Paste into your AI client's MCP settings +4. Your client connects directly to Nexus servers + +### Supported clients: +- Claude Desktop +- Claude.ai (Web) +- Goose +- Any client with "remote MCP URL" or "HTTP connector" options + +### Advantages: +- ✅ **Simplest setup** - just copy and paste +- ✅ **No local software** needed +- ✅ **Automatic updates** - always uses latest version +- ✅ **Works across devices** - same URL everywhere + +### Connection flow: +``` +Your AI Client ←→ Internet ←→ Nexus Servers ←→ Your Tools +``` + +## Hub Bridge Method + +**Local proxy connection** for clients that only support local MCP servers. + +### How it works: +1. Configure your client to run `npx -y @civic/hub-bridge` as a local MCP server +2. Your client thinks it's connecting to a local server +3. The bridge forwards requests to Nexus servers +4. Bridge handles all authentication and token management + +### Supported clients: +- Cursor (one-click install) +- VS Code (one-click install) +- JetBrains IDEs (manual setup) +- Windsurf (manual setup) +- Claude Code (auto-install: `npx @civic/hub-bridge install claude-code`) +- Any client with only "local MCP" or "stdio" options + +### Advantages: +- ✅ **Universal compatibility** - works with any MCP client +- ✅ **Local control** - bridge runs on your machine +- ✅ **Transparent authentication** - handles OAuth flows automatically +- ✅ **Offline capability** - cached tokens work briefly offline + +### Connection flow: +``` +Your AI Client ←→ Hub Bridge (local) ←→ Internet ←→ Nexus Servers ←→ Your Tools +``` + +## How to Tell Which Method You Need + +### Check your AI client's settings: + +**Use Remote URL if you see:** +- "Remote MCP server" +- "HTTP MCP URL" +- "MCP connector URL" +- "External MCP server" + +**Use Hub Bridge if you see:** +- "Local MCP server" +- "Command/stdio" +- "MCP executable" +- "Local process" + +### Quick test: +If your client asks for a command and arguments (like `npx` and `[@civic/hub-bridge]`), you need Hub Bridge. If it asks for a URL, you can use Remote URL. + +## Why Two Methods? + +### MCP Client Limitations + +Not all AI clients support all MCP features: + +**Remote URL requirements:** +- HTTP/HTTPS network requests +- OAuth authentication handling +- Token refresh management +- Remote server connections + +**Hub Bridge compatibility:** +- Only needs local process spawning +- Bridge handles all network complexity +- Works with any stdio-based MCP client + +### Technical Differences + +**Remote URL clients:** +- Native MCP HTTP protocol support +- Built-in OAuth handling +- Direct network connectivity +- Usually newer or more advanced clients + +**Hub Bridge clients:** +- stdio/process-based MCP only +- No built-in authentication +- Local-only MCP support +- Often development tools or older clients + +## Authentication Differences + +### Remote URL Authentication: +- Your client handles OAuth directly +- You authorize in your client's interface +- Client manages token storage and refresh + +### Hub Bridge Authentication: +- Bridge handles all OAuth flows +- You authorize in your browser (opened by bridge) +- Bridge manages tokens locally and refreshes automatically + +## When to Use Each Method + +### Choose Remote URL when: +- Your client supports it (check settings for "remote MCP URL") +- You want the simplest setup +- You use multiple devices +- You prefer cloud-based management + +### Choose Hub Bridge when: +- Your client only supports local/stdio MCP +- You're using development tools (IDEs, CLIs) +- You want local control over connections +- Your client doesn't support OAuth + +## Troubleshooting Connection Issues + +### Remote URL problems: +- **Client doesn't connect**: Check if client supports remote MCP URLs +- **Authentication fails**: Verify client has OAuth capabilities +- **URL not accepted**: Try Hub Bridge method instead + +### Hub Bridge problems: +- **Command not found**: Install Node.js 18+ +- **Bridge won't start**: Check terminal permissions and network access +- **Authentication hangs**: Ensure browser can open and corporate firewalls aren't blocking + +## Both Methods Work the Same + +Once connected, **your AI experience is identical** regardless of connection method: +- Same tools and capabilities +- Same authentication to individual services +- Same performance and reliability +- Same security and privacy protections + +The connection method is just plumbing - what matters is that your AI can access your tools! \ No newline at end of file diff --git a/nexus/concepts/mcp.mdx b/nexus/concepts/mcp.mdx new file mode 100644 index 00000000..706ac3b3 --- /dev/null +++ b/nexus/concepts/mcp.mdx @@ -0,0 +1,178 @@ +--- +title: What is MCP? +description: A beginner's guide to the Model Context Protocol and why it powers Nexus +icon: "circle-info" +--- + +## The Problem: AI That's Cut Off From Your World + +Your AI assistant is smart, but it's trapped. It can't check your GitHub repos, send Slack messages, or read your Dropbox files. It only knows what was in its training data - nothing about your specific work, tools, or data. + +This is like having a brilliant research assistant who's locked in a room with no internet, phone, or access to your company's systems. They can think deeply about problems, but they can't help with anything that requires real information or actions. + +## The Solution: Model Context Protocol (MCP) + +**MCP is like giving your AI assistant API keys to your digital life** - but done safely and with your control. + +Think of MCP as a universal translator that lets any AI assistant talk to any tool or service, whether it's GitHub, Slack, your database, or a custom internal tool. + +### The Simple Version + +Before MCP: +``` +You: "Check my GitHub pull requests" +AI: "I can't access external services. You'll need to check GitHub yourself." +``` + +After MCP: +``` +You: "Check my GitHub pull requests" +AI: [Uses GitHub MCP server] "You have 3 open PRs: 'Add user auth' needs review, 'Fix login bug' has conflicts, and 'Update docs' is ready to merge." +``` + +## How MCP Works: The 30-Second Version + +1. **MCP Servers** = Tools that do things (like a GitHub server that can create issues) +2. **MCP Clients** = AI assistants that want to use tools (like Claude) +3. **MCP Protocol** = The language they use to talk to each other + +``` +Your AI (Client) ←→ MCP Protocol ←→ Your Tools (Servers) +``` + +When you ask your AI to "create a GitHub issue," here's what happens: +1. AI says "I need to use the GitHub tool" +2. MCP makes sure you've authorized GitHub access +3. AI sends the request through MCP to GitHub +4. GitHub creates the issue and responds back +5. AI tells you "Done! Issue #123 created." + +## What Makes MCP Special + +### 1. **Universal Connection** +One protocol works with everything - no matter if it's GitHub, Slack, your database, or a tool your team built last week. + +### 2. **Built for AI** +Unlike regular APIs, MCP is designed specifically for AI assistants. It includes: +- Descriptions so AI knows what each tool does +- Examples so AI knows how to use tools properly +- Safety features to prevent AI from doing harmful things + +### 3. **You Stay in Control** +- You choose which tools to connect +- You authorize what the AI can access +- You can revoke access anytime +- You can see everything the AI does + +### 4. **Secure by Design** +- AI never gets your actual passwords or API keys +- All connections are encrypted +- You can set limits on what AI can do +- Full audit trail of all actions + +## Real Examples That Make Sense + +### For Developers +**Before:** "I need to manually check GitHub, then update Slack, then update my task tracker..." +**After:** "AI, check all my repos for failing tests, create issues for the failures, and notify my team on Slack." + +### For Marketing Teams +**Before:** "Let me log into 5 different tools to pull this week's metrics..." +**After:** "AI, pull this week's email metrics, social media stats, and website analytics, then create a summary report." + +### For Sales Operations +**Before:** "I need to update the CRM, then check the calendar, then send follow-up emails..." +**After:** "AI, find all prospects who haven't responded in 2 weeks and draft personalized follow-up emails." + +## The Technical Details (For Those Who Want Them) + +MCP defines three types of things AI can work with: + +### Tools +Functions the AI can call, like: +- `create_github_issue(title, description)` +- `send_slack_message(channel, text)` +- `query_database(sql)` + +### Resources +Data sources the AI can read from, like: +- File systems +- Database contents +- API endpoints +- Live data feeds + +### Prompts +Pre-written instructions that help AI use tools better, like: +- "Here's how to write good GitHub issues" +- "Follow this format when posting to Slack" + +## Security: The Stuff That Keeps You Safe + +### Authentication +AI has to prove it's allowed to use your tools before it gets access. + +### Authorization +Even after connecting, you control exactly what the AI can do. Examples: +- ✅ "AI can read my GitHub repos" +- ❌ "AI cannot delete repositories" +- ✅ "AI can send messages to #general Slack channel" +- ❌ "AI cannot create new Slack channels" + +### Audit Logging +Every single thing the AI does gets logged so you can see: +- What tool was used +- When it was used +- What data was accessed +- What actions were taken + +## How Nexus Uses MCP + +**Civic Nexus is an MCP service** - we've built the infrastructure so you don't have to: + +- **Dozens of Pre-built MCP Servers**: GitHub, Slack, Dropbox, databases, and more +- **Secure Connection Management**: We handle OAuth, tokens, and security +- **Simple Setup**: Just copy one URL or install one package +- **Enterprise Security**: Encryption, compliance, audit logs + +Instead of setting up individual MCP servers yourself, you connect to Nexus and get access to everything through one secure connection. + +## What This Means for You + +### If You're New to AI Tools +MCP turns AI assistants from "smart chatbots" into "digital team members" who can actually do work across all your tools. + +### If You're Technical +MCP is the missing piece that makes AI assistants genuinely useful for real work instead of just answering questions. + +### If You Manage Teams +MCP enables AI-powered automation that works across your entire tool stack, turning hours of manual work into minutes of AI-assisted workflows. + +## Getting Started + +Ready to see what AI can do when it's connected to your tools? + + + Get up and running in 5 minutes with the most popular setup + + + + See dozens of MCP servers with hundreds of tools you can connect + + +## Questions? + + +No - MCP is specifically designed for AI. Regular APIs don't include the descriptions, examples, and safety features that AI needs to use tools effectively and safely. + + + +You control every connection. Start with read-only access to non-sensitive tools, then expand as you get comfortable. You can revoke access instantly anytime. + + + +Those are automation platforms where you pre-define workflows. MCP lets AI create workflows dynamically based on what you ask for in natural language. + + + +Not at all. If you can use Slack or Gmail, you can use MCP. The technical complexity is hidden - you just talk to your AI in plain English. + \ No newline at end of file diff --git a/nexus/concepts/oauth.mdx b/nexus/concepts/oauth.mdx new file mode 100644 index 00000000..5cf71481 --- /dev/null +++ b/nexus/concepts/oauth.mdx @@ -0,0 +1,86 @@ +--- +title: OAuth & Authentication +description: How Nexus securely connects to your apps without storing passwords +icon: "shield-check" +--- + +## What is OAuth? + +OAuth is a secure way for apps to access your accounts in other services without ever seeing your password. When you connect Nexus to GitHub, Slack, or Dropbox, you're using OAuth. + +## How It Works + +Instead of giving Nexus your GitHub password, OAuth works like this: + + + + Nexus says "I'd like to access your GitHub repos" + + + GitHub asks you "Allow Nexus to access your repos?" and you click "Yes" + + + GitHub gives Nexus a special token (not your password) that proves you said "yes" + + + Nexus uses the token to access your repos on your behalf + + + +## Why OAuth is Safer + +**With passwords:** +- ❌ Apps store your actual password +- ❌ If they get hacked, your password is exposed +- ❌ Hard to revoke access +- ❌ App can do anything your account can do + +**With OAuth:** +- ✅ Apps never see your password +- ✅ You can revoke access anytime +- ✅ Limited permissions (read repos, not delete account) +- ✅ Tokens expire automatically + +## OAuth in Nexus + +When you first use a tool in Nexus: + +1. **Chat Interface**: Your AI will ask you to authorize the service +2. **Quick Authorization**: Click to approve the specific permissions needed +3. **One-Time Setup**: You only need to do this once per service +4. **Automatic Management**: Nexus handles token refresh and renewal + +## Managing Your Authorizations + +You can always: +- **View connected services** in your Nexus dashboard +- **Revoke access** to any service instantly +- **Re-authorize** if you need different permissions +- **See what permissions** each service has + +## Common Questions + + +The service immediately stops working in your AI assistant. You can re-authorize it anytime by using a command that requires that service. + + + +No, never. Nexus only stores OAuth tokens, which are secure, limited-permission keys that don't contain any password information. + + + +Yes! During the OAuth flow, you can often choose which permissions to grant. For example, you might allow read access to repositories but not write access. + + + +OAuth tokens typically last 1-24 hours before automatic refresh. If you don't use a service for extended periods, you may need to re-authorize. + + +## Security Best Practices + +- **Review permissions** before clicking "Authorize" +- **Revoke unused services** periodically in your Nexus dashboard +- **Use specific permissions** rather than granting broad access +- **Monitor your connected services** to ensure you recognize them all + +OAuth keeps your accounts secure while letting your AI assistant do useful work across all your tools. \ No newline at end of file diff --git a/nexus/concepts/toolkits.mdx b/nexus/concepts/toolkits.mdx new file mode 100644 index 00000000..32b600ec --- /dev/null +++ b/nexus/concepts/toolkits.mdx @@ -0,0 +1,227 @@ +--- +title: Toolkits +description: Create focused groups of MCP servers for specific tasks and workflows +icon: "toolbox" +--- + +## What are Toolkits? + +Toolkits allow you to create focused groups of MCP servers that work together for specific tasks or workflows. Instead of connecting to all your available tools at once (which can confuse AI assistants), toolkits let you create targeted combinations optimized for particular use cases. + + +**Why use toolkits?** When AI assistants have access to too many tools at once, they can struggle to choose the right ones. Toolkits solve this by creating focused, task-specific tool groups. + + + + Civic Nexus toolkit interface showing organized tool groups + + +## Common Toolkit Examples + + + + **Tools:** Google Analytics + Notion + Slack + + Perfect for marketing teams who need to pull analytics data, document insights, and share reports with the team. + + + + **Tools:** GitHub + PostgreSQL + Notion + + Ideal for developers who need to investigate issues, query databases, and document solutions. + + + + **Tools:** Linear + GitHub + Slack + + Great for product teams managing feature requests, code reviews, and team communication. + + + + **Tools:** Notion + HubSpot + Slack + + Excellent for support teams who need to access customer data, update tickets, and coordinate responses. + + + +## How to Create a Toolkit + +Creating a toolkit takes just a few steps and lets you build focused tool groups for your specific workflows. + + + + Click the **"+ Create toolkit"** button in the top navigation, next to your current toolkit name. + + + Nexus interface showing the Create toolkit button in the navigation + + + + + Give your toolkit a descriptive name and URL alias. This helps you and your team understand what the toolkit is designed for. + + + Create New Toolkit dialog showing name and URL alias fields + + + **Example names:** + - "Marketing Redshift" (for marketing analytics) + - "Debug Kit" (for development troubleshooting) + - "Content Pipeline" (for content creation workflow) + + + + Once created, you'll get a unique URL for your toolkit that you can use in any MCP-compatible client. + + + Toolkit setup page showing the unique MCP URL for the toolkit + + + **Toolkit URL format:** + ``` + https://nexus.civic.com/hub/mcp?profile=your-toolkit-name + ``` + + **Default URL (all tools):** + ``` + https://nexus.civic.com/hub/mcp + ``` + + + +## Using Toolkits in AI Clients + +You have two main ways to work with toolkits: + +### Method 1: Direct URL Connection + +Use your toolkit's specific URL when setting up MCP connections in clients like Claude Desktop, Cursor, or VS Code. + +``` +https://nexus.civic.com/hub/mcp?profile=marketing-redshift +``` + +This will connect your AI client to only the tools in that specific toolkit. + +### Method 2: Switch Toolkits in Nexus UI + +If you're using Nexus Chat or managing multiple toolkits, you can switch between them using the dropdown in the Nexus interface. Simply select the toolkit you want to use from the toolkit selector in the top navigation. + +## Toolkit Management + + + + Navigate to your toolkit and click "Add Tools" to select from your connected services. You can add or remove tools anytime without affecting your AI client connections. + + + + Click on your toolkit name to edit it. The URL alias will update automatically, but existing connections will continue to work. + + + + Toolkit URLs are tied to your account's authentication. Team members will need their own toolkit configurations, but you can share the concept and tool combinations. + + + + - **Default URL:** Gives access to ALL your connected tools + - **Toolkit URL:** Gives access to ONLY the tools in that specific toolkit + - You can use both simultaneously in different AI clients + + + +## Best Practices + + +Follow these guidelines to get the most out of your toolkits: + + +### Keep Toolkits Focused +- **3-5 tools maximum** per toolkit for best AI performance +- Choose tools that naturally work together for specific workflows +- Avoid mixing unrelated tools (e.g., don't combine crypto data with marketing analytics) + +### Use Descriptive Names +- **Good:** "Customer Support Kit", "Marketing Analytics", "Dev Debug Tools" +- **Avoid:** "My Tools", "Work Stuff", "Toolkit 1" + +### Organize by Workflow, Not by Service +- **Think workflow:** "Content creation process" → Linear + GitHub + Slack +- **Don't think service:** "All my productivity tools" → 15+ different services + +### Test Your Combinations +- Try asking your AI to perform typical tasks with your toolkit +- Adjust the tool combination if the AI seems confused or chooses wrong tools +- Remove tools that don't add value to the specific workflow + +## Common Toolkit Patterns + +Based on popular MCP server combinations, here are proven toolkit patterns: + + + + **Pattern:** Data source + Documentation + Communication + + **Examples:** + - Google Analytics + Notion + Slack + - PostgreSQL + Linear + GitHub + - CoinGecko + Notion + Discord + + + + **Pattern:** Code repository + Database + Issue tracking + + **Examples:** + - GitHub + PostgreSQL + Linear + - GitHub + Sentry + Notion + - GitHub + HubSpot + Slack + + + + **Pattern:** CRM + Documentation + Communication + + **Examples:** + - HubSpot + Notion + Slack + - ActiveCampaign + Linear + GitHub + - Dropbox + HubSpot + Notion + + + +## Next Steps + + + + Identify a specific workflow or task you do regularly that involves 3-5 tools + + + + Follow the steps above to create a focused toolkit for that workflow + + + + Use your toolkit with your preferred AI assistant and adjust the tool combination as needed + + + + Build additional toolkits for other workflows once you've validated the first one + + + + + Join our developer community if you need assistance creating effective toolkits for your workflows + diff --git a/nexus/concepts/tools-resources-prompts.mdx b/nexus/concepts/tools-resources-prompts.mdx new file mode 100644 index 00000000..b5441cd8 --- /dev/null +++ b/nexus/concepts/tools-resources-prompts.mdx @@ -0,0 +1,131 @@ +--- +title: Tools, Resources & Prompts +description: The three types of capabilities your AI can access through MCP +icon: "toolbox" +--- + +## The Three Types of MCP Capabilities + +When you connect to an MCP server (like GitHub or Slack), your AI gets access to three types of capabilities: + +## Tools 🔧 + +**Tools are actions your AI can perform** - things that change or do something. + +### Examples: +- **GitHub**: Create an issue, merge a pull request, comment on code +- **Slack**: Send a message, create a channel, react to posts +- **Dropbox**: Upload a document, share a file, organize files in folders +- **Email**: Send an email, mark as read, move to folder + +### How your AI uses tools: +``` +You: "Create a GitHub issue for the login bug" +AI: [Uses GitHub create_issue tool] "Issue #123 created: Fix login bug" + +You: "Send a Slack message to the team" +AI: [Uses Slack send_message tool] "Message sent to #general" +``` + +## Resources 📄 + +**Resources are information your AI can read** - things that provide data. + +### Examples: +- **GitHub**: Repository contents, issue descriptions, commit history +- **Slack**: Message history, channel member lists, thread contents +- **Dropbox**: File contents, folder structures, file metadata +- **Databases**: Query results, table schemas, stored data + +### How your AI uses resources: +``` +You: "What's in our latest pull request?" +AI: [Reads GitHub PR resource] "The PR adds user authentication with OAuth..." + +You: "Summarize yesterday's Slack messages" +AI: [Reads Slack message history resource] "Main topics discussed: deployment, bug fixes..." +``` + +## Prompts 💭 + +**Prompts are pre-written instructions** that help your AI use tools and resources effectively. + +### Examples: +- **Code Review Prompt**: "Review this pull request for security issues, performance, and code style" +- **Bug Report Prompt**: "Create a detailed bug report with steps to reproduce, expected vs actual behavior" +- **Meeting Summary Prompt**: "Summarize key decisions, action items, and next steps from this conversation" + +### How your AI uses prompts: +``` +You: "Review this pull request" +AI: [Uses code review prompt] Systematically checks security, performance, style, and provides structured feedback + +You: "Summarize today's standup" +AI: [Uses meeting summary prompt] Creates organized summary with decisions, action items, blockers +``` + +## How They Work Together + +A typical AI workflow combines all three: + + + + AI reads current state (GitHub issues, Slack messages, file contents) + + + AI applies pre-written instructions for how to analyze or process the information + + + AI takes actions based on what it learned (create issues, send messages, update files) + + + +### Example Workflow: +``` +You: "Prepare for our team standup" + +1. AI reads resources: Recent GitHub commits, Slack messages, project files +2. AI uses prompt: "Standup preparation checklist" +3. AI uses tools: Creates summary document, posts reminder in Slack +``` + +## Understanding MCP Server Capabilities + +Each MCP server provides different combinations: + +### GitHub Server +- **Tools**: Create issues, comment, merge PRs, create branches +- **Resources**: Repository files, issue lists, commit history, PR details +- **Prompts**: Code review templates, issue creation guidelines + +### Slack Server +- **Tools**: Send messages, create channels, react to posts, set status +- **Resources**: Message history, channel lists, user profiles, thread contents +- **Prompts**: Message formatting, team communication guidelines + +### Dropbox Server +- **Tools**: Upload documents, search files, organize folders +- **Resources**: File contents, folder structures, sharing permissions +- **Prompts**: Document creation templates, organization standards + +## Why This Matters + +Understanding these three types helps you: + +- **Ask better questions**: "Read the latest GitHub issues" (resource) vs "Create a new issue" (tool) +- **Set expectations**: Know what your AI can read vs what it can change +- **Troubleshoot**: If something isn't working, understand whether it's a tool, resource, or prompt issue +- **Explore capabilities**: Ask "What tools are available?" to discover what actions your AI can take + +## Discovering Available Capabilities + +Try these prompts to explore what's available: + +``` +"What tools can you use?" +"What information can you access?" +"What prompts are available for GitHub?" +"Show me all the Slack capabilities" +``` + +Your AI will list the tools, resources, and prompts available from your connected MCP servers, helping you understand what's possible. \ No newline at end of file diff --git a/nexus/configuring-tools.mdx b/nexus/configuring-tools.mdx new file mode 100644 index 00000000..d21d58b8 --- /dev/null +++ b/nexus/configuring-tools.mdx @@ -0,0 +1,286 @@ +--- +title: Configuring Your Tools +description: How to select and set up MCP servers on nexus.civic.com and in chat +icon: "cog" +--- + +## Two Ways to Configure Tools + +You can configure which tools your AI assistant can access in two ways: + +1. **On nexus.civic.com** - Browse and select tools before connecting your AI +2. **In AI chat** - Configure tools directly in conversation after connecting + +## Method 1: Web Configuration (nexus.civic.com) + +### Browse Available Tools + +Visit **nexus.civic.com** to see dozens of available MCP servers: + + + Nexus MCP directory showing categorized tools + + +- **Development**: GitHub, GitLab, Linear, Jira +- **Communication**: Slack, Discord, Telegram +- **Productivity**: Dropbox, Notion, Airtable +- **Databases**: PostgreSQL, MySQL, SQLite +- **Marketing**: ActiveCampaign, HubSpot, Mailchimp +- **And many more...** + +### Select Your Tools + + + + Tools are organized by category (Development, Communication, etc.) for easy discovery + + Tool categories in the MCP directory + + + + Click on any tool to add it to your configuration + + Adding tools to your configuration + + + + See your selected tools in the sidebar before connecting + + Sidebar showing selected tools + + + + Copy your MCP URL or Hub Bridge installation command + + Copy connection URL or install command + + + + +### Benefits of Web Configuration + +- **Visual browsing** of all available tools +- **Detailed descriptions** of what each tool does +- **Pre-selection** before connecting your AI +- **Easy management** of your tool collection + +## Method 2: In-Chat Configuration + +After connecting your AI client to Nexus, you can configure tools directly in conversation: + +### Adding New Tools + +``` +"Connect me to GitHub and Slack" +"Add the PostgreSQL server for our database" +"Show me what tools are available to connect" +"I need access to Dropbox" +``` + +### Managing Existing Tools + +``` +"What tools do I have connected?" +"Disconnect from Slack" +"Show me my GitHub connection status" +"Update my database connection settings" +``` + +### Discovery and Help + +``` +"What MCP servers are available?" +"How do I connect to Notion?" +"What can I do with the GitHub integration?" +"Help me set up ActiveCampaign" +``` + +### Benefits of Chat Configuration + +- **Natural language** setup process +- **Contextual** tool selection based on your current task +- **Just-in-time** configuration when you need specific tools +- **Guided setup** with AI assistance + +## Authentication Process + +Regardless of how you configure tools, you'll need to authenticate: + + + + When you first use a tool, you'll be prompted to authorize access + + + A browser window opens to the service's authentication page + + + Review and approve the specific permissions your AI will have + + + Close the browser and return to your AI - the tool is now connected + + + + +**One-time setup**: You only need to authenticate each tool once. Nexus securely manages tokens and handles refresh automatically. + + +## Managing Your Configuration + +### View Connected Tools + +Ask your AI: +``` +"What tools do I have access to?" +"Show my connected services" +"List my MCP servers" +``` + +### Update Tool Settings + +Some tools allow configuration updates: +``` +"Change my Slack default channel to #general" +"Update my GitHub repository filter" +"Show PostgreSQL connection settings" +``` + +### Remove Tools + +``` +"Disconnect from Slack" +"Remove the PostgreSQL server" +"Revoke GitHub access" +``` + + +Removing a tool will immediately revoke its access and require re-authentication if you want to use it again. + + +## Tool-Specific Configuration + +Some tools have specific configuration options: + +### GitHub +- Repository access (public, private, or specific repos) +- Organization permissions +- Webhook settings for real-time updates + +### Slack +- Workspace access +- Channel permissions (read, write, manage) +- Bot capabilities + +### Databases (PostgreSQL, MySQL, etc.) +- Connection strings +- Read-only vs read-write access +- Query timeout settings +- Schema restrictions + +### Dropbox +- Folder access permissions +- File type restrictions +- Sharing capabilities + +## Best Practices + +### Start Small +Begin with 2-3 essential tools rather than connecting everything at once. This makes it easier to: +- Learn how each integration works +- Troubleshoot any issues +- Build confidence with AI tool usage + +### Review Permissions +When authenticating, carefully review what access you're granting: +- ✅ Read access to public repositories +- ⚠️ Write access to important data +- ❌ Admin permissions unless necessary + +### Regular Audits +Periodically review your connected tools: +``` +"Show me what tools I have connected" +"When did I last use each tool?" +"What permissions have I granted?" +``` + +### Use Descriptive Requests +Be specific when adding tools: +- Instead of: "Add GitHub" +- Try: "Connect to GitHub so I can manage issues in my work repositories" + +This helps ensure you get the right level of access for your needs. + +## Common Configuration Scenarios + +### For Developers +``` +"Connect me to GitHub, Linear, and Slack" +"Add PostgreSQL access for our main database" +"Set up the staging environment database connection" +``` + +### For Marketing Teams +``` +"Connect ActiveCampaign and Dropbox" +"Add HubSpot for our CRM data" +"Set up Slack for team notifications" +``` + +### For Operations Teams +``` +"Connect to our Dropbox and HubSpot for document management" +"Add Slack and Notion for team coordination" +"Set up database access for reporting" +``` + +## Troubleshooting Configuration + +### Tool Won't Connect +1. Check if the service is supported on nexus.civic.com +2. Verify you have the necessary permissions in the service +3. Try disconnecting and reconnecting +4. Check the troubleshooting guide for service-specific issues + +### Authentication Fails +1. Ensure you're logged into the service in your browser +2. Check for popup blockers preventing OAuth windows +3. Try using an incognito/private browser window +4. Contact the service administrator if using enterprise accounts + +### Tool Not Appearing in Chat +1. Verify the tool is actually connected: "What tools do I have?" +2. Try refreshing your AI client connection +3. Check if the tool requires specific activation steps +4. Restart your AI client if using Hub Bridge + +## Need Help? + + + + Browse all available tools with detailed setup guides + + + Common configuration issues and solutions + + \ No newline at end of file diff --git a/nexus/developers/client-setup.mdx b/nexus/developers/client-setup.mdx new file mode 100644 index 00000000..4a753a3a --- /dev/null +++ b/nexus/developers/client-setup.mdx @@ -0,0 +1,220 @@ +--- +title: Developer Client Setup +description: Advanced setup guides for development tools and IDEs +icon: "code" +--- + +## Overview + +This section covers setup for development tools and IDEs that require more technical configuration than the primary ChatGPT/Claude clients. + + +**New to Civic Nexus?** Start with [Claude Desktop](/nexus/quickstart/clients/claude-desktop) for the simplest setup experience, then add development tools later. + + +## Prerequisites + +All development tools require: + + + + Required for the Hub Bridge - check with node --version + + + Free signup - authenticate development tools via OAuth + + + +## Quick Start (2 Options) + +### Option 1: Direct HTTP Connection + + + + Visit [nexus.civic.com](https://nexus.civic.com) and copy your personal MCP endpoint URL + + + Add the HTTP endpoint directly to your development tool's MCP configuration + + + Follow OAuth prompts when first using any server - tokens are securely stored + + + +### Option 2: Hub Bridge (Local Proxy) + + + + Add `npx -y @civic/hub-bridge` as your MCP server command in client settings + + + Run any MCP command - OAuth browser window opens automatically for first-time setup + + + Hub Bridge handles authentication and routes requests to your selected Civic Nexus servers + + + + +**Performance:** HTTP endpoints are faster. **Compatibility:** Hub Bridge works with more clients that don't support HTTP endpoints yet. + + +## Cursor Setup + +**Most Popular Development Tool** - AI-powered code editor with excellent MCP support. + + + **One-click install available** - Complete walkthrough with troubleshooting and testing steps + + +**Quick Summary:** +- ✅ One-click install button available +- ✅ Node.js 18+ required +- ✅ Works with free and paid Cursor plans +- ⏱️ Setup time: 2 minutes + +## VS Code Setup + +**Industry Standard Editor** - Support for both HTTP connectors and Hub Bridge method. + + + **Multiple setup methods** - HTTP connector, Hub Bridge, and one-click install options + + +**Quick Summary:** +- ✅ Remote HTTP connector support (recommended) +- ✅ Hub Bridge fallback method available +- ✅ One-click install link included +- ⏱️ Setup time: 2 minutes + +--- + + + Having setup issues? Join our developer community for assistance with your development environment. + + +--- + +## Client Compatibility + +### AI-First Code Editors + + + + **Setup Time:** 3 minutes + **Method:** One-click install or Hub Bridge + **HTTP Support:** ✅ Via Hub Bridge + + + **Setup Time:** 3 minutes + **Method:** Hub Bridge configuration + **HTTP Support:** ❌ Requires Hub Bridge + + + +### Traditional IDEs + + + + **3 minutes** - HTTP endpoint or Hub Bridge + + + **5 minutes** - Hub Bridge via MCP plugin + + + **Advanced setup** - Community MCP plugins + + + +### Command Line Tools + + + + **2 minutes** - HTTP endpoint support + + + **Coming Soon** - Direct integration planned + + + **Coming Soon** - MCP support planned + + + +--- + +## JetBrains IDEs Setup + +**Enterprise Development Environment** - Full IDE suite with robust MCP plugin support. + + + **Plugin-based setup** - Step-by-step guide for IntelliJ, PyCharm, WebStorm, and all JetBrains IDEs + + +**Quick Summary:** +- ✅ Supports all JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.) +- ✅ MCP plugin available in marketplace +- ✅ Hub Bridge integration method +- ⏱️ Setup time: 2 minutes + +--- + +## Windsurf Setup + +**Codeium AI IDE** - Modern AI-powered development environment with MCP support. + + + **Hub Bridge method** - Configuration steps for Windsurf's MCP integration + + +**Quick Summary:** +- ✅ Codeium AI IDE integration +- ✅ Hub Bridge configuration required +- ✅ JSON-based setup process +- ⏱️ Setup time: 2 minutes + +--- + +## Goose Setup + +**Block's Developer Agent** - Command-line AI assistant with direct HTTP endpoint support. + + + **Direct HTTP support** - No Hub Bridge needed, direct MCP URL configuration + + +**Quick Summary:** +- ✅ Direct HTTP endpoint support (no Hub Bridge needed) +- ✅ YAML configuration file setup +- ✅ Advanced toolkit configurations available +- ⏱️ Setup time: 2 minutes + +--- + +## Best Practices + +### Development Workflow + +1. **Start simple** - Use one server first (like GitHub or Slack) +2. **Test incrementally** - Add one server at a time +3. **Monitor usage** - Check your Civic Nexus dashboard for activity +4. **Update regularly** - Keep Hub Bridge updated with `npm update -g @civic/hub-bridge` + +### Team Collaboration + +**For teams using the same tools:** + +1. **Commit config files** to version control (they don't contain secrets) +2. **Document setup** in your project README +3. **Use consistent naming** across team members +4. **Share tool selections** - use same Civic Nexus server selection + +### Security Considerations + +- **Hub Bridge runs locally** - tokens never leave your machine except to make API calls +- **Tokens are encrypted** using OS-level key storage +- **OAuth scopes are minimal** - only request necessary permissions +- **Revoke access anytime** at nexus.civic.com + + + Complete security documentation and compliance information + \ No newline at end of file diff --git a/nexus/developers/client-setup.mdx.backup b/nexus/developers/client-setup.mdx.backup new file mode 100644 index 00000000..f8c48a56 --- /dev/null +++ b/nexus/developers/client-setup.mdx.backup @@ -0,0 +1,476 @@ +--- +title: Developer Client Setup +description: Advanced setup guides for development tools and IDEs +icon: "code" +--- + +## Overview + +This section covers setup for development tools and IDEs that require more technical configuration than the primary ChatGPT/Claude clients. + + +**New to Civic Nexus?** Start with [Claude Desktop](/nexus/quickstart/clients/claude-desktop) for the simplest setup experience, then add development tools later. + + +## Prerequisites + +All development tools require: + + + + Required for the Hub Bridge - check with node --version + + + Create account and select your tools at nexus.civic.com + + + +## How Developer Setup Works + +### Option 1: Remote HTTP Endpoints (Newer Clients) + +Some development tools now support direct HTTP connections: + + + + Sign in to nexus.civic.com and copy: https://nexus.civic.com/hub/mcp + + + Add the URL as an HTTP endpoint in your client settings + + + OAuth authentication happens directly through the browser + + + +**Clients with HTTP support:** VS Code, Goose + +### Option 2: Hub Bridge (Traditional Method) + +Most development tools still require the **Hub Bridge** method: + + + + Add a JSON configuration that tells your IDE to run npx @civic/hub-bridge + + + Hub Bridge handles OAuth flows and server selection automatically + + + Your IDE connects to Civic Nexus tools through the local bridge + + + + +**Why Hub Bridge?** Some development tools only support local MCP servers, so the bridge acts as a secure proxy between your IDE and Civic Nexus. + + +## Supported Development Tools + +### AI-First Code Editors + + + + **Setup Time:** 3 minutes + **Method:** One-click install or JSON config + **Best For:** AI-assisted development + + + **Setup Time:** 5 minutes + **Method:** JSON configuration + **Best For:** Codeium AI development + + + +### Traditional IDEs + + + + **3 minutes** - HTTP endpoint or Hub Bridge + + + **5 minutes** - Manual configuration + + + **5 minutes** - Plugin + JSON + + + +### Command Line Tools + + + + **2 minutes** - HTTP endpoint support + + + **5 minutes** - Hub Bridge + + + **5 minutes** - Hub Bridge + + + +--- + +## Cursor Setup {#cursor} + +**Recommended:** Use the one-click install for fastest setup. + +### Method 1: One-Click Install (Easiest) + + + + + Add Civic Nexus to Cursor + + + + + When Cursor opens, click "Install" to add the Civic Nexus MCP server + + + + Try: "What MCP servers are available?" in Cursor's chat + + + +### Method 2: Manual Configuration + + + + Create .cursor/mcp.json in your project root: + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] + } + } + } + ``` + + + + Save the file and restart Cursor + + + + + Complete setup guide with troubleshooting + + +--- + +## VS Code Setup {#vscode} + +**VS Code now supports both remote HTTP endpoints and Hub Bridge.** + +### Method 1: Remote HTTP Endpoint (Recommended) + + + + Sign in to [nexus.civic.com](https://nexus.civic.com) and copy: https://nexus.civic.com/hub/mcp + + + + 1. Open VS Code Settings (File > Preferences > Settings) + 2. Search for "MCP" + 3. Add server with Type: **http**, URL: https://nexus.civic.com/hub/mcp + + + + Try: "What MCP servers are available?" in VS Code's AI features + + + +### Method 2: Hub Bridge (Alternative) + + + + +
+ 📦 Add to VS Code (Hub Bridge) +
+ + + + + In VS Code Settings, search for "MCP" and enable required options + + + + Try MCP commands in VS Code's AI chat features + + + +### Method 3: Manual Configuration + + + + Create .mcp.json in your workspace root: + ```json + { + "servers": { + "civic-nexus": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] + } + } + } + ``` + + + + Save the file and restart VS Code + + + + + Complete setup guide with troubleshooting + + +--- + +## JetBrains IDEs Setup {#jetbrains} + +**Supported:** IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, etc. + + + + 1. Go to **Settings > Plugins** + 2. Search for "MCP" and install the MCP plugin + 3. Restart your IDE + + + + 1. Go to **Settings > MCP Servers** + 2. Click **Add Server** + 3. Configure: + - **Name:** Civic Nexus + - **Command:** npx -y @civic/hub-bridge + - **Type:** stdio + + + + Enable the server and test with AI features in your IDE + + + + + IDE-specific setup instructions + + +--- + +## Other Development Tools + +### Windsurf (Codeium AI IDE) {#windsurf} + + + + Add to Windsurf's MCP configuration: + ```json + { + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] + } + ``` + + + + + Detailed Windsurf setup instructions + + +### Goose (Block's Developer Agent) {#goose} + +**Goose now supports direct HTTP endpoints without Hub Bridge.** + + + + Sign in to [nexus.civic.com](https://nexus.civic.com) and copy: https://nexus.civic.com/hub/mcp + + + + Add to your Goose config (typically ~/.config/goose/config.yaml): + ```yaml + mcp: + servers: + civic-nexus: + type: http + url: https://nexus.civic.com/hub/mcp + name: "Civic Nexus" + ``` + + + + Restart Goose and try: "What MCP servers are available?" + + + + + Direct URL setup for Goose + + +--- + +## Hub Bridge Deep Dive + +### What is Hub Bridge? + +Hub Bridge (@civic/hub-bridge) is a local Node.js application that: + +- **Translates protocols:** Converts between stdio MCP (used by IDEs) and HTTP MCP (used by Civic Nexus) +- **Handles authentication:** Manages OAuth flows and token storage locally +- **Provides security:** Encrypts tokens and manages secure connections +- **Auto-updates:** Downloads and updates itself automatically + +### How It Works + +**Data Flow:** +```text +[Your IDE] -> [Hub Bridge] -> [Civic Nexus] -> [GitHub/Slack/etc.] + Local Process Cloud Service External Services +``` + +1. **Your IDE** runs npx @civic/hub-bridge as a local MCP server +2. **Hub Bridge** receives commands via stdio and forwards them to Civic Nexus via HTTP +3. **Civic Nexus** executes commands on connected services using stored OAuth tokens +4. **Results** flow back through the same path + +### Configuration Options + +The Hub Bridge supports these environment variables: + +```bash +# Custom cache directory (optional) +export CIVIC_BRIDGE_CACHE_DIR=/custom/path + +# Debug mode (optional) +export CIVIC_BRIDGE_DEBUG=true + +# Custom auth timeout (optional) +export CIVIC_BRIDGE_AUTH_TIMEOUT=300 +``` + + + Detailed Hub Bridge documentation and troubleshooting + + +--- + +## Troubleshooting + +### Common Setup Issues + + + + **Error:** "npx: command not found" or "'node' is not recognized" + + **Solution:** + - Install Node.js 18+ from [nodejs.org](https://nodejs.org) + - Restart your terminal/IDE after installation + - Verify: node --version and npm --version + + + + **Error:** Permission errors when running npx @civic/hub-bridge + + **Solution:** + - Don't use sudo - npm should work without admin privileges + - Check npm permissions: npm config get prefix + - Fix npm permissions or use a Node version manager like nvm + + + + **Error:** Bridge process exits immediately or shows errors + + **Solution:** + - Check Node.js version (must be 18+) + - Clear npm cache: npm cache clean --force + - Try manual install: npm install -g @civic/hub-bridge + - Check for corporate proxy/firewall blocking npm + + + + **Error:** OAuth flows fail or loop indefinitely + + **Solution:** + - Create account at [nexus.civic.com](https://nexus.civic.com) first + - Check that default browser is set correctly + - Corporate networks: try from personal network initially + - Clear browser cache for civic.com domains + + + +### Getting Help + + + + - Node.js version: node --version (must be 18+) + - Hub Bridge status: npx @civic/hub-bridge --help + - Network connectivity to nexus.civic.com + + + + Enable debug mode and check logs: + ```bash + export CIVIC_BRIDGE_DEBUG=true + npx @civic/hub-bridge + ``` + + + + If issues persist, contact support with: + - Your IDE/client type and version + - Node.js version + - Any error messages + - Debug logs (if available) + + + + + Contact our team with your specific development setup questions + + +--- + +## Best Practices + +### Project-Level Configuration + +**Recommended:** Use project-level MCP configuration files: + +- **Cursor:** .cursor/mcp.json in project root +- **VS Code:** .mcp.json in workspace root +- **JetBrains:** Per-project settings in .idea/ folder + +This allows different projects to have different MCP server configurations. + +### Team Collaboration + +**For teams using the same tools:** + +1. **Commit config files** to version control (they don't contain secrets) +2. **Document setup** in your project README +3. **Use consistent naming** across team members +4. **Share tool selections** - use same Civic Nexus server selection + +### Security Considerations + +- **Hub Bridge runs locally** - tokens never leave your machine except to make API calls +- **Tokens are encrypted** using OS-level key storage +- **OAuth scopes are minimal** - only request necessary permissions +- **Revoke access anytime** at nexus.civic.com + + + Complete security documentation and compliance information + diff --git a/nexus/developers/vercel-ai-sdk.mdx b/nexus/developers/vercel-ai-sdk.mdx new file mode 100644 index 00000000..da3bd3a6 --- /dev/null +++ b/nexus/developers/vercel-ai-sdk.mdx @@ -0,0 +1,342 @@ +--- +title: Vercel AI SDK Integration +description: Build AI applications using Civic Nexus with Vercel AI SDK +icon: "triangle" +--- + +## Overview + +Integrate Civic Nexus with Vercel AI SDK to build AI applications that can access external tools and services through MCP (Model Context Protocol). This enables your AI agents to interact with GitHub, Slack, Dropbox, and other connected services. + + +**Updated for AI SDK v5**: This guide has been updated to use Vercel AI SDK v5. The main changes from v4 include: +- New tool definition format with `execute` functions +- Updated streaming response methods (`toDataStreamResponse()` instead of `toAIStreamResponse()`) +- Improved error handling and type safety +- App Router examples instead of Pages Router + + + +**Prerequisites:** You'll need a Civic account and Node.js 18+ installed. [Create your account](https://nexus.civic.com) and select your tools first. + + +## Installation + +Install the required packages: + +```bash +npm install ai @ai-sdk/openai @ai-sdk/anthropic @modelcontextprotocol/sdk @civic/auth +``` + + +**AI SDK v5**: This guide uses the latest Vercel AI SDK v5, which includes significant improvements and breaking changes from v4. Make sure to use v5 for the best experience. + + + + + Latest AI SDK for building AI applications + + + OpenAI and Anthropic provider packages + + + Provides HTTP client transport for MCP protocol + + + Handles authentication with Civic Nexus + + + +## Basic Setup + +### Step 1: Create MCP Client + +Create a function to initialize the MCP client with authentication: + +```typescript +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { getTokens } from "@civic/auth/nextjs"; + +const createMCPClient = async () => { + // Get access token from Civic Auth + const { accessToken } = await getTokens(); + + if (!accessToken) { + throw new Error('No access token available. User needs to authenticate.'); + } + + // Create transport with authentication + const transport = new StreamableHTTPClientTransport( + 'https://nexus.civic.com/hub/mcp', + { + requestInit: { + headers: { + Authorization: `Bearer ${accessToken}`, + 'Content-Type': 'application/json' + } + } + } + ); + + // Initialize MCP client + const client = new Client({ + name: 'my-ai-app', + version: '1.0.0' + }, { + capabilities: {} + }); + + await client.connect(transport); + return client; +}; +``` + +### Step 2: List Available Tools + +Query available MCP tools from your connected services: + +```typescript +const listAvailableTools = async () => { + const client = await createMCPClient(); + + try { + const tools = await client.listTools(); + console.log('Available tools:', tools.tools); + return tools.tools; + } catch (error) { + console.error('Failed to list tools:', error); + throw error; + } finally { + await client.close(); + } +}; +``` + +### Step 3: Call MCP Tools + +Execute tools with the MCP client: + +```typescript +const callMCPTool = async (toolName: string, arguments: Record) => { + const client = await createMCPClient(); + + try { + const result = await client.callTool({ + name: toolName, + arguments + }); + + return result.content; + } catch (error) { + console.error(`Failed to call tool ${toolName}:`, error); + throw error; + } finally { + await client.close(); + } +}; +``` + +## Integration with Vercel AI SDK + +### Using with OpenAI + +Combine MCP tools with OpenAI's function calling: + +```typescript +import { openai } from '@ai-sdk/openai'; +import { generateText } from 'ai'; + +const generateWithMCPTools = async (prompt: string) => { + // Get available MCP tools + const client = await createMCPClient(); + const { tools } = await client.listTools(); + + // Convert MCP tools to AI SDK v5 tool format + const aiTools = tools.reduce((acc, tool) => { + acc[tool.name] = { + description: tool.description, + parameters: tool.inputSchema, + execute: async (args: any) => { + // Execute MCP tool when called + return await callMCPTool(tool.name, args); + } + }; + return acc; + }, {} as Record); + + const result = await generateText({ + model: openai('gpt-4'), + prompt, + tools: aiTools, + }); + + await client.close(); + return result; +}; +``` + +### Using with Anthropic Claude + +```typescript +import { anthropic } from '@ai-sdk/anthropic'; +import { generateText } from 'ai'; + +const generateWithClaude = async (prompt: string) => { + const client = await createMCPClient(); + const { tools } = await client.listTools(); + + // Convert MCP tools to AI SDK v5 tool format + const aiTools = tools.reduce((acc, tool) => { + acc[tool.name] = { + description: tool.description, + parameters: tool.inputSchema, + execute: async (args: any) => { + // Execute MCP tool when called + return await callMCPTool(tool.name, args); + } + }; + return acc; + }, {} as Record); + + const result = await generateText({ + model: anthropic('claude-3-5-sonnet-20241022'), + prompt, + tools: aiTools, + }); + + await client.close(); + return result; +}; +``` + +## Complete Example: AI Assistant + +Here's a complete example showing how to authenticate with Nexus and integrate MCP tools: + +```typescript +// app/api/chat/route.ts (Next.js App Router API route) +import { NextRequest } from 'next/server'; +import { openai } from '@ai-sdk/openai'; +import { streamText } from 'ai'; +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { getTokens } from "@civic/auth/nextjs"; + +async function createMCPClient() { + // Get Civic Auth token for Nexus authentication + const { accessToken } = await getTokens(); + + // Create MCP transport with Nexus authentication headers + const transport = new StreamableHTTPClientTransport( + 'https://nexus.civic.com/hub/mcp', + { + requestInit: { + headers: { + // Required: Bearer token for Nexus authentication + Authorization: `Bearer ${accessToken}`, + 'Content-Type': 'application/json' + } + } + } + ); + + const client = new Client({ + name: 'my-ai-app', + version: '1.0.0' + }, { + capabilities: {} + }); + + await client.connect(transport); + return client; +} + +export async function POST(req: NextRequest) { + const { messages } = await req.json(); + + // Connect to Nexus MCP Hub + const client = await createMCPClient(); + const { tools } = await client.listTools(); + + // Convert MCP tools to AI SDK v5 format + const aiTools = tools.reduce((acc, tool) => { + acc[tool.name] = { + description: tool.description, + parameters: tool.inputSchema, + execute: async (args: any) => { + const result = await client.callTool({ + name: tool.name, + arguments: args + }); + return result.content; + } + }; + return acc; + }, {} as Record); + + const result = await streamText({ + model: openai('gpt-4'), + messages, + tools: aiTools, + }); + + await client.close(); + return result.toDataStreamResponse(); +} +``` + +## Nexus Authentication + +The key to integrating with Nexus is properly setting up the authentication headers. Here's what you need: + + + + ```typescript + headers: { + // Required: Bearer token from Civic Auth + Authorization: `Bearer ${accessToken}`, + 'Content-Type': 'application/json' + } + ``` + + + + Use Civic Auth to get the user's access token: + ```typescript + import { getTokens } from "@civic/auth/nextjs"; + const { accessToken } = await getTokens(); + ``` + + + + Always connect to the Nexus MCP Hub endpoint: + ``` + https://nexus.civic.com/hub/mcp + ``` + + + +## Next Steps + + + + Configure Civic Auth in your Next.js application following our [auth guide](/integration/nextjs) + + + + Visit [nexus.civic.com](https://nexus.civic.com) to connect GitHub, Slack, or other services + + + + Use the examples above to create your AI-powered application + + + + Deploy to Vercel or your preferred platform with proper environment variables + + + + + Join our developer community for technical support and implementation assistance + diff --git a/nexus/overview.mdx b/nexus/overview.mdx new file mode 100644 index 00000000..9cc277bf --- /dev/null +++ b/nexus/overview.mdx @@ -0,0 +1,235 @@ +--- +title: Welcome to Civic Nexus +description: Connect your AI assistant to dozens of MCP servers with hundreds of tools +icon: "rocket" +public: false +--- + +## What is Civic Nexus? + +**Civic Nexus connects your AI assistant to all your tools** - GitHub, Slack, Dropbox, databases, and dozens of other services. Your AI can finally do real work instead of just answering questions. + +## How It Works + +### Easiest Way: Try It Directly in Nexus Chat + + + + Create your account and browse dozens of available MCP servers (GitHub, Slack, Dropbox, etc.) + + Nexus directory showing available tools + + + + Use the built-in chat interface - no setup required, start testing tools right away + + Nexus chat interface ready to use + + + + Request tools and authorizations directly in chat: "Connect me to GitHub", "Check my Slack messages" + + OAuth authorization flow in chat + + + + Your AI assistant can now access your tools - all within the Nexus interface + + AI assistant showing results from connected tools + + + + +### Optional: Connect External AI Clients + +Once you've tested in Nexus chat, you can connect external clients like Claude and development tools for convenience. + + +**No server management, no API keys to juggle, no complex configurations.** + + + + + **2 minutes** - Most popular AI client + + + **2 minutes** - Development IDE integration + + + **2 minutes** - AI-powered code editor + + + +## Ready to Get Started? + + + + **Fastest way** - No setup required, start using tools immediately + + + **For convenience** - Use ChatGPT, Claude, or development tools + + + + +**Start with Nexus chat first** - Test all tools directly in our interface, then optionally connect external AI clients for convenience. + + +## What You Can Do + +Once connected, your AI can work with all your tools: + + + + ``` + "Check my open GitHub pull requests" + "Create an issue for the login bug with debugging details" + "Send a Slack message when the deployment finishes" + ``` + + + ``` + "Summarize today's Slack messages in #general" + "Create a report from our PostgreSQL sales data" + "Find all files updated in Dropbox this week" + ``` + + + ``` + "Update our ActiveCampaign email list with new signups" + "Create HubSpot contact records from this lead sheet" + "Send campaign performance data to our Slack marketing channel" + "Generate a report of this month's Mailchimp engagement metrics" + ``` + + + ``` + "Sync CRM data with our HubSpot revenue tracking" + "Create Linear tickets for sales process improvements" + "Update Airtable with quarterly pipeline metrics" + "Send weekly revenue summary to #revenue-ops Slack" + ``` + + + +## Organize Tools with Toolkits + +Create focused groups of tools for specific workflows instead of overwhelming your AI with every available service. + + +**Why toolkits matter:** When AI assistants have access to too many tools at once, they often choose the wrong ones or get confused. Toolkits solve this by creating focused, task-specific tool groups. + + + + + **Google Analytics + Notion + Slack** for pulling data, documenting insights, and sharing reports + + + **GitHub + PostgreSQL + Notion** for investigating issues, querying databases, and documenting solutions + + + + + Create focused tool groups that help your AI work more effectively on specific tasks + + +## Security + + + Your data security is our top priority. Civic Nexus is designed for more secure infrastructure with encrypted credential management and proactive server security reviews. + + +🔒 **Secure by Design** - All tokens encrypted, automatic refresh, stringent infrastructure +⚡ **Full Control** - Revoke app access instantly, changes apply immediately +🛡️ **Encrypted Ease of Development** - Streamlined development with stringent security standards + + + Learn about our security architecture, compliance, and best practices + + +## All Supported Clients + +### Primary AI Assistants + + + **Available** • Direct connector • 2 mins + + + **Available** • Direct connector • 2 mins + + + **Available** • Direct connector • 2 mins + + + +### Development Tools + + **Cursor, VS Code, JetBrains IDEs, and more** - Advanced setup guides for development environments + + + +**Primary vs Development:** Primary clients offer simple direct connector setup. Development tools require Hub Bridge configuration but offer the same functionality. + + +## Get Started Right Now + + + **Zero setup required** - Sign up and start using hundreds of tools in our built-in chat interface + + + + Step-by-step guides for ChatGPT, Claude, VS Code, and more + + +## Available Tools & Services + +Connect to dozens of popular MCP servers with hundreds of tools: + + + + Manage repos, create issues, review PRs + + + Send messages, search conversations + + + Access files, upload documents + + + Manage databases, create pages + + + +**Plus:** ActiveCampaign, PostgreSQL, HubSpot, Airtable, Linear, and many more. + + + Complete directory of MCP servers with setup guides + + +## Need Help? + + + + Common setup issues and solutions + + + Get help with your specific setup + + + diff --git a/nexus/quickstart/clients/chatgpt.mdx b/nexus/quickstart/clients/chatgpt.mdx new file mode 100644 index 00000000..63a1c246 --- /dev/null +++ b/nexus/quickstart/clients/chatgpt.mdx @@ -0,0 +1,191 @@ +--- +title: ChatGPT Setup +description: Connect ChatGPT to Civic Nexus - Coming Soon +icon: "message-circle" +--- + + +**ChatGPT connector support is coming soon!** We're working on full integration with ChatGPT's MCP connector system. Expected availability: Q1 2026. + + +## What's Coming + +ChatGPT will support direct MCP connections to Civic Nexus, making it as simple as Claude Desktop's setup: + + + ChatGPT MCP connector interface preview + + +### Expected Features + +✅ **Direct connector support** - No technical setup required +✅ **One-click authentication** - Authorize tools directly in chat +✅ **All Civic Nexus tools** - Full access to GitHub, Slack, Dropbox, and dozens of other services +✅ **Real-time updates** - Get notified when new tools become available +✅ **Stringent security** - Same security standards as our Claude integration + +## Alternative: Use Claude Desktop Now + +While we wait for ChatGPT support, Claude Desktop offers the same simple connector experience: + + + + **Available now** - 2-minute setup with direct connectors + + + **Available now** - No download required, works in browser + + + +## Expected Setup Process + +When ChatGPT connector support launches, setup will be similar to Claude: + + + + Navigate to **Settings → Integrations → MCP Connectors** + + + ChatGPT settings showing MCP connectors option + + + + + Click **Add Connector** and enter: `https://nexus.civic.com/hub/mcp` + + + ChatGPT add connector dialog with Nexus URL + + + + + Choose from GitHub, Slack, Dropbox, and dozens of other services + + + Tool selection interface showing available services + + + + + Ask ChatGPT to use your connected tools in plain English + + + ChatGPT chat showing tool usage + + + + +## Common Questions + + + + We're targeting Q1 2026 for full ChatGPT MCP connector support. We'll announce updates on our website and through email notifications. + + + + ChatGPT connector support will be included with all existing Civic Nexus plans at no additional cost. + + + + Yes, enterprise customers will have full connector support with additional security and compliance features. + + + + We'll offer a beta program for early access. Join our waitlist to be notified when it becomes available. + + + +## Get Notified + + + Be the first to know when ChatGPT connector support launches + + +## Try It Today with Claude + +Don't want to wait? Get started immediately with Claude Desktop: + + + + [Claude Desktop](/nexus/quickstart/clients/claude-desktop) offers the same experience you'll get with ChatGPT + + + Connect to hundreds of Civic Nexus tools with the same 2-minute setup + + + When ChatGPT support launches, you can easily switch or use both clients + + + +## Troubleshooting (When Available) + +When ChatGPT connector support launches, here are common issues to watch for: + + + + **Problem:** "Unauthorized" or "Authentication failed" when connecting + + **Solutions when available:** + - Make sure you're signed into your ChatGPT account + - Check that MCP connectors are enabled in your ChatGPT subscription + - Try removing and re-adding the Civic Nexus connector + - Clear browser cache and cookies if using ChatGPT web + + + + **Problem:** "Connector not found" or "Invalid URL" error + + **Solutions when available:** + - Double-check the URL: `https://nexus.civic.com/hub/mcp` + - Ensure you have a valid Civic Nexus account at nexus.civic.com + - Try the setup process again from the beginning + - Join our developer community if the issue persists + + + + **Problem:** Connected but can't see or use tools + + **Solutions when available:** + - Ask ChatGPT: "What MCP connectors are available?" + - Check that you selected tools during the Nexus setup process + - Try authorizing individual services: "Connect me to GitHub" + - Restart ChatGPT or refresh the browser page + + + +## Need Help Now? + + + + Get started immediately with the same tools and experience + + + Questions about ChatGPT support or early access + + + See what you'll be able to connect when ChatGPT support launches + + + Learn about our stringent security standards + + diff --git a/nexus/quickstart/clients/claude-code.mdx b/nexus/quickstart/clients/claude-code.mdx new file mode 100644 index 00000000..3efe800a --- /dev/null +++ b/nexus/quickstart/clients/claude-code.mdx @@ -0,0 +1,34 @@ +--- +title: Claude Code Setup +description: Connect Anthropic's Claude Code CLI to Civic Nexus +icon: "terminal" +--- + + + Claude Code setup instructions coming soon... + + +## Overview + +Claude Code (Anthropic's command-line coding assistant) requires the Hub Bridge method for connecting to Civic Nexus MCP servers. + +## Coming Soon + +Detailed setup instructions for Claude Code configuration are being prepared. + +## Resources + + + + Essential Hub Bridge setup for Claude Code + + + Claude Code MCP support details + + + Common Claude Code connection issues + + + Join our developer community for Claude Code setup help + + diff --git a/nexus/quickstart/clients/claude-desktop.mdx b/nexus/quickstart/clients/claude-desktop.mdx new file mode 100644 index 00000000..d06dd42c --- /dev/null +++ b/nexus/quickstart/clients/claude-desktop.mdx @@ -0,0 +1,280 @@ +--- +title: Claude Desktop Setup +description: Connect Claude Desktop to Civic Nexus in 5 minutes +icon: "desktop" +--- + + + This guide covers Claude Desktop setup. For other AI clients, see our [client compatibility guide](/nexus/reference/client-compatibility). + + +## Prerequisites + +Before you begin, make sure you have: + + + + Download and install Claude Desktop (Pro or Team plan required for MCP connectors) + + + Create a free account on nexus.civic.com + + + +## Step 1: Copy the MCP URL + + + + Open [nexus.civic.com](https://nexus.civic.com) and sign in with your Civic account. + + + Browse and select the MCP servers you want to connect (GitHub, Slack, Dropbox, etc.) + + + Copy this URL: `https://nexus.civic.com/hub/mcp` + + + Civic Nexus homepage + + + + +## Step 2: Add MCP Server in Claude Desktop + + + + 1. In Claude Desktop, click on **Settings** (usually in the bottom left or profile menu) + 2. Navigate to **Connectors** + + + Claude Desktop settings page with Connectors section highlighted + + + + + 1. Click **"Add Custom Connector"** + 2. Enter a name: **"Civic Nexus"** + 3. In "Remote MCP server URL" field, paste: `https://nexus.civic.com/hub/mcp` + 4. Click **"Add"** to confirm + + + Claude Desktop connector settings dialog + + + + + 1. The connector will appear in your list with a **"Connect"** button + 2. Click **"Connect"** to begin authentication + 3. Follow on-screen instructions to authorize access to your selected services + 4. Return to **Settings > Connectors** to verify it shows as "Connected" + + + Claude Desktop showing connected Civic Nexus connector + + + + +## Step 3: Test Your Connection + +Try these commands to verify everything is working: + +``` +"What MCP servers are available?" +"Check my GitHub repositories" +"What's in my Dropbox?" +"Show recent Slack messages" +``` + + + Claude Desktop chat showing successful tool usage + + +## Managing Your Tools + +### Adding More Tools + +You can add new tools directly in your Claude Desktop chat: + +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"I need access to Dropbox" +"Show me what tools are available to connect" +``` + +Claude will handle the connection process and guide you through any required authentication steps. + +### Alternative Method: Hub Bridge (Free Users) + +If you don't have Claude Pro, Team, or Enterprise, you won't have access to MCP connectors in the UI. Use Hub Bridge instead: + + +**Free Claude users**: The MCP connector UI is only available on paid Claude plans. Use this method if you're on the free plan. + + + + + 1. In Claude Desktop, go to **Settings** + 2. Click the **Developer** tab + 3. Click **Edit Config** to open `claude_desktop_config.json` + + + + Add this to your config file: + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + + This uses the **Hub Bridge** method which works with any Claude Desktop version, including free. + + + + + 1. Save the config file + 2. **Restart Claude Desktop** for changes to take effect + + + + When you first use an MCP command: + 1. Create account at **[nexus.civic.com](https://nexus.civic.com)** and select your tools + 2. The Hub Bridge will handle authentication automatically + + + +### Removing Tools + +You can disconnect from specific tools directly in chat: + +``` +"Disconnect from Slack" +"Remove GitHub from my tools" +"What tools do I currently have connected?" +"Stop my access to Dropbox" +``` + +### Managing the Entire Connector + +To remove the Civic Nexus connector completely: + + + + Go to **Settings > Connectors** in Claude Desktop + + + 1. Find "Civic Nexus" in your connectors list + 2. Click **Remove** or **Delete** next to the connector + 3. Confirm the removal when prompted + + + Visit [nexus.civic.com](https://nexus.civic.com) to revoke service authorizations if you no longer want Civic to have access + + + +## Common Questions + + + + Yes, MCP connectors are currently only available on Claude Pro and Team plans. The free Claude plan doesn't support external integrations. + + + + If you encounter authentication issues: + - Make sure you're logged into the correct account for the service + - Check if your account email matches between nexus.civic.com and the service + - Try removing and re-adding the MCP connector with a fresh URL + - Check our [troubleshooting guide](/nexus/troubleshooting) for more solutions + + + + If your nexus.civic.com account uses a different email than your connected services (e.g., work@company.com vs personal@gmail.com), make sure you authenticate with the correct account for each service during the OAuth flow. + + + + Try these steps: + - Update Claude Desktop to the latest version + - Remove the connector completely and re-add with a fresh MCP URL + - Check that your system allows Claude network access + - Restart Claude Desktop after making changes + + + +## Two-Minute Verification + +Once connected, test these prompts to make sure everything works: + + + + ``` + "List my GitHub repositories" + "Show me my recent pull requests" + "What issues are assigned to me?" + ``` + + + ``` + "What are the recent messages in #general?" + "List my Slack workspaces" + "Send a test message to myself" + ``` + + + ``` + "What files are in my Dropbox?" + "Show me recently modified documents" + "Search for files containing 'project'" + ``` + + + +## Need Help? + + + Solutions for common Claude Desktop connection issues + + +## Next Steps + +Now that you're connected, explore what you can do: + + + + Add more MCP servers to expand Claude's capabilities + + + Learn how Nexus keeps your data secure + + + See setup guides for other AI clients + + + Join our developer community if you need help + + diff --git a/nexus/quickstart/clients/claude-web.mdx b/nexus/quickstart/clients/claude-web.mdx new file mode 100644 index 00000000..3912a03b --- /dev/null +++ b/nexus/quickstart/clients/claude-web.mdx @@ -0,0 +1,192 @@ +--- +title: Claude.ai (Web) Setup +description: Connect Claude.ai web interface to Civic Nexus +icon: "globe" +--- + + + Claude.ai web interface supports direct MCP server connections. You'll need a Claude Pro or Team plan to access MCP connectors. + + +## Prerequisites + + + + MCP connectors require a paid Claude subscription + + + Create a free account on nexus.civic.com + + + +## Step 1: Copy the MCP URL + + + + Open [nexus.civic.com](https://nexus.civic.com) and sign in with your Civic account. + + + Browse and select the MCP servers you want to connect (GitHub, Slack, Dropbox, etc.) + + + Copy this URL: `https://nexus.civic.com/hub/mcp` + + + Civic Nexus homepage + + + + +## Step 2: Add MCP Server in Claude.ai + + + + 1. Go to [claude.ai](https://claude.ai) in your web browser + 2. Click on **Settings** (usually in the bottom left or profile menu) + 3. Navigate to **Connectors** + + + Claude.ai settings page with Connectors section highlighted + + + + + 1. Click **"Add Custom Connector"** + 2. Enter a name: **"Civic Nexus"** + 3. In "Remote MCP server URL" field, paste: `https://nexus.civic.com/hub/mcp` + 4. Click **"Add"** to confirm + + + Claude.ai connector settings dialog + + + + + 1. The connector will appear in your list with a **"Connect"** button + 2. Click **"Connect"** to begin authentication + 3. Follow on-screen instructions to authorize access to your selected services + 4. Return to **Settings > Connectors** to verify it shows as "Connected" + + + Claude.ai showing connected Civic Nexus connector + + + + +## Step 3: Test Your Connection + +Try these commands to verify everything is working: + +``` +"What MCP servers are available?" +"Check my GitHub repositories" +"What's in my Dropbox?" +"Show recent Slack messages" +``` + + + Claude.ai chat showing successful tool usage + + +## Managing Your Tools + +### Adding More Tools + +You can add new tools directly in your Claude.ai chat: + +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"I need access to Dropbox" +"Show me what tools are available to connect" +``` + +Claude will handle the connection process and guide you through any required authentication steps. + +### Removing Tools + +To disconnect from specific tools, just ask in chat: + +``` +"Disconnect from Slack" +"Remove GitHub from my tools" +"What tools do I currently have connected?" +"Stop my access to Dropbox" +``` + +### Managing the Entire Connector + +To remove the Civic Nexus connector completely: + + + + Go to **Settings > Connectors** in Claude.ai + + + 1. Find "Civic Nexus" in your connectors list + 2. Click **Remove** or **Delete** next to the connector + 3. Confirm the removal when prompted + + + Visit [nexus.civic.com](https://nexus.civic.com) to revoke service authorizations if you no longer want Civic to have access + + + +## Common Questions + + + + Yes, MCP connectors are only available on Claude Pro and Team plans. The free plan doesn't support external integrations. + + + + - Make sure you're signed into the correct accounts for your connected services + - Try removing and re-adding the connector with a fresh URL from nexus.civic.com + - Check our [troubleshooting guide](/nexus/troubleshooting) for more solutions + + + + Yes! You can add multiple MCP connectors from different providers. Each will appear separately in your connectors list. + + + + Data flows directly between Claude.ai and your connected services through Civic Nexus. See our [security details](/nexus/reference/security) for more information. + + + +## Need Help? + + + + Solutions for common connection issues + + + See all available MCP servers you can connect + + + Learn how Nexus protects your data + + + Contact us for personalized help + + diff --git a/nexus/quickstart/clients/cursor.mdx b/nexus/quickstart/clients/cursor.mdx new file mode 100644 index 00000000..91e073df --- /dev/null +++ b/nexus/quickstart/clients/cursor.mdx @@ -0,0 +1,211 @@ +--- +title: Cursor Setup +description: Connect Cursor AI code editor to Civic Nexus in 3 minutes +icon: "code" +--- + +## Prerequisites + + + + Download and install Cursor (free tier works) + + + Required for the Hub Bridge - check with `node --version` + + + +## Setup Steps + + + + Use the one-click install button below: + + + Add Civic Nexus to Cursor + + + + + When Cursor opens, click "Install" to add the Civic Nexus MCP server + + + + Make sure Civic Nexus is enabled in Cursor's MCP settings. If you don't see it, try disabling and re-enabling it. + + + + The first time you use any MCP command, the Hub Bridge will: + - Automatically download and install itself + - Handle authentication directly in the chat interface + - Let you select which tools to connect from nexus.civic.com + + + +## Test Your Connection + +Try these prompts in Cursor to verify everything works: + +``` +"What MCP servers are available?" +"Show me my connected tools" +"Help me set up GitHub integration" +``` + +## Troubleshooting + + +Make sure Cursor is installed and try copying this URL manually: +``` +cursor://anysphere.cursor-deeplink/mcp/install?name=Civic%20Nexus&config=eyJjb21tYW5kIjoibnB4IC15IEBjaXZpYy9odWItYnJpZGdlIn0%3D +``` + + + +Install Node.js 18 or later from [nodejs.org](https://nodejs.org) and restart Cursor. + + + +The Hub Bridge should handle authentication in the chat. If it doesn't: +1. Restart Cursor +2. Try disabling and re-enabling Civic Nexus in Cursor settings +3. Make sure you're trying to use a tool that requires authentication + + + +1. Make sure you clicked "Install" when prompted +2. Check Cursor's MCP server settings manually +3. Try the manual setup method below + + +## Manual Setup (If One-Click Fails) + +If the one-click install doesn't work, add Civic Nexus manually: + +### Method 1: Via Cursor Settings (Recommended) + + + + Go to **Settings → Features → MCP** + + + + 1. Click **+ Add New MCP Server** + 2. Select transport type: **stdio** + 3. Enter nickname: **Civic Nexus** + 4. Enter command: **npx -y @civic/hub-bridge** + 5. Save the configuration + + + + The server should appear in your MCP servers list. Test with: "What MCP servers are available?" + + + +### Method 2: Via Configuration File + + + + Create a file called **`.cursor/mcp.json`** in your project root directory + + + + Add the following content: + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] + } + } + } + ``` + + + + Save the file and restart Cursor. The MCP server will be automatically detected. + + + + Test with: "What MCP servers are available?" + + + +## Managing Your Tools + +### Adding More Tools + +You can add new tools directly in your Cursor chat: + +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"I need access to PostgreSQL" +"Show me what tools are available to connect" +``` + +Cursor will handle the connection process and guide you through any required authentication steps. + +### Removing Tools + +You can disconnect from specific tools directly in chat: + +``` +"Disconnect from Slack" +"Remove GitHub from my tools" +"What tools do I currently have connected?" +"Stop my access to Dropbox" +``` + +### Removing the MCP Server + +To remove Civic Nexus completely: + +**Via Settings:** + + + Go to **Settings → Features → MCP** + + + 1. Find "Civic Nexus" in your MCP servers list + 2. Click on the server to access its settings + 3. Click **Delete** or **Remove** button + + + +**Via Configuration File:** + + + Open your **`.cursor/mcp.json`** file + + + Delete the `"civic-nexus"` entry from the `mcpServers` object + + + Save the file and restart Cursor + + + +## Resources + + + + Detailed Hub Bridge setup and troubleshooting + + + Technical details about Cursor's MCP support + + + Common Cursor connection issues + + + Join our developer community for setup assistance + + diff --git a/nexus/quickstart/clients/gemini.mdx b/nexus/quickstart/clients/gemini.mdx new file mode 100644 index 00000000..fa074f79 --- /dev/null +++ b/nexus/quickstart/clients/gemini.mdx @@ -0,0 +1,34 @@ +--- +title: Gemini CLI Setup +description: Connect Google's Gemini CLI tool to Civic Nexus +icon: "google" +--- + + + Gemini CLI setup instructions coming soon... + + +## Overview + +Gemini CLI requires the Hub Bridge method for connecting to Civic Nexus MCP servers. + +## Coming Soon + +Detailed setup instructions for Gemini CLI configuration are being prepared. + +## Resources + + + + Essential Hub Bridge setup for CLI tools + + + Gemini CLI MCP support details + + + Common CLI tool connection issues + + + Join our developer community for Gemini CLI help + + diff --git a/nexus/quickstart/clients/goose.mdx b/nexus/quickstart/clients/goose.mdx new file mode 100644 index 00000000..f72dae5d --- /dev/null +++ b/nexus/quickstart/clients/goose.mdx @@ -0,0 +1,128 @@ +--- +title: Goose Setup +description: Connect Goose autonomous developer agent to Civic Nexus +icon: "terminal" +--- + +## Overview + +Goose (Block's autonomous developer agent) now supports direct remote HTTP endpoints for connecting to Civic Nexus MCP servers with full OAuth2 support. + +## Prerequisites + + + + Install Goose autonomous developer agent + + + Create a free account on nexus.civic.com + + + +## Setup with Remote HTTP Endpoint + + + + 1. Sign in to [nexus.civic.com](https://nexus.civic.com) + 2. Select the MCP servers you want to use + 3. Copy the MCP URL: `https://nexus.civic.com/hub/mcp` + + + + Add the Civic Nexus MCP server to your Goose configuration: + + 1. Open your Goose configuration file (typically `~/.config/goose/config.yaml` or project-specific `.goose/config.yaml`) + 2. Add the following MCP server configuration: + + ```yaml + mcp: + servers: + civic-nexus: + type: http + url: https://nexus.civic.com/hub/mcp + name: "Civic Nexus" + ``` + + + Goose supports HTTP endpoints directly, no local bridge required. + + + + + Restart Goose to load the new configuration: + ```bash + goose restart + ``` + Or if running as a service: + ```bash + goose stop + goose start + ``` + + + + Verify the connection is working: + ``` + "What MCP servers are available?" + "Show me my connected tools" + ``` + + Goose should respond with the list of available Civic Nexus tools. + + + + When you first use a tool that requires authentication: + 1. Goose will prompt you to authorize access + 2. A browser window will open for OAuth authentication + 3. Sign in to the service and authorize access + 4. Return to Goose when complete + + + Authentication is handled securely by Civic Nexus. Your credentials are never exposed to Goose or stored locally. + + + + +## Alternative: Hub Bridge Setup + +If you prefer to use the local Hub Bridge instead of direct HTTP endpoints: + + + + Add this to your Goose configuration: + + ```yaml + mcp: + servers: + civic-nexus: + type: stdio + command: npx + args: ["-y", "@civic/hub-bridge"] + ``` + + + + Make sure Node.js 18+ is installed for the Hub Bridge to work + + + + Restart Goose and test with: "What MCP servers are available?" + + + +## Resources + + + + Goose MCP support details (Remote URL method) + + + Similar Remote URL setup process + + + Common connection issues + + + Join our developer community for Goose setup help + + diff --git a/nexus/quickstart/clients/jetbrains.mdx b/nexus/quickstart/clients/jetbrains.mdx new file mode 100644 index 00000000..9640000d --- /dev/null +++ b/nexus/quickstart/clients/jetbrains.mdx @@ -0,0 +1,47 @@ +--- +title: JetBrains IDEs Setup +description: Connect JetBrains IDEs (IntelliJ, PyCharm, WebStorm) to Civic Nexus +icon: "command" +--- + + + JetBrains IDE setup instructions coming soon... + + +## Overview + +JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) require the Hub Bridge method for connecting to Civic Nexus MCP servers. + +## Configuration Required + +JetBrains IDEs need manual MCP server configuration with these settings: + +```json +{ + "name": "Civic Nexus", + "type": "stdio", + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] +} +``` + +## Coming Soon + +Detailed setup instructions with IDE-specific screenshots and configuration steps are being prepared. + +## Resources + + + + Essential Hub Bridge setup for JetBrains IDEs + + + JetBrains MCP support details + + + Common JetBrains connection issues + + + Join our developer community for JetBrains setup help + + diff --git a/nexus/quickstart/clients/mistral-lechat.mdx b/nexus/quickstart/clients/mistral-lechat.mdx new file mode 100644 index 00000000..5e8b776e --- /dev/null +++ b/nexus/quickstart/clients/mistral-lechat.mdx @@ -0,0 +1,295 @@ +--- +title: Mistral LeChat Setup +description: Connect Mistral LeChat to Civic Nexus in 5 minutes +icon: "sparkles" +--- + + + This guide covers Mistral LeChat setup. For other AI clients, see our [client compatibility guide](/nexus/reference/client-compatibility). + + +## Prerequisites + +Before you begin, make sure you have: + + + + Access to Mistral LeChat at chat.mistral.ai + + + Create a free account on nexus.civic.com + + + +## Step 1: Copy the MCP URL + + + + Open [nexus.civic.com](https://nexus.civic.com) in your browser and sign in with your Civic account. + + Civic Nexus homepage + + + + Explore the directory of available MCP servers. Each server connects to a different service or tool. + + + Popular servers include Slack, GitHub, Dropbox, and Notion. Click on any server to see what it can do. + + + + + Click the checkbox next to each MCP server you want to use. You can select multiple servers. + + + Some servers may require authentication with the service they connect to. Make sure you have access to accounts for the services you select. + + + + + After selecting servers, copy this URL: + ``` + https://nexus.civic.com/hub/mcp + ``` + + + + +## Step 2: Add Connector to LeChat + + + + In LeChat: + 1. Look at the **left-hand sidebar** + 2. Click on the **"Intelligence"** tab + 3. This will open the Intelligence settings panel + + + LeChat showing Intelligence tab in left sidebar + + + + + 1. In the Intelligence panel, click on **"Connectors"** + 2. This will show your existing connectors and options to add new ones + + + LeChat Connectors section in Intelligence settings + + + + + 1. Click **"Add Connector"** button + 2. Select **"Custom MCP"** from the connector types + 3. Enter the following information: + - **Name**: "Civic Nexus" + - **MCP URL**: `https://nexus.civic.com/hub/mcp` + - **Description** (optional): "Access hundreds of tools via Civic Nexus" + 4. Click **"Connect"** to save the connector + + + LeChat Custom MCP connector dialog + + + + +## Step 3: Authenticate and Test + + + + When you first use an MCP server that requires authentication: + 1. LeChat will prompt you to connect to the service + 2. A browser window will open for OAuth authentication + 3. Sign in to the service and authorize access + 4. Return to LeChat when complete + + + GitHub OAuth authorization screen + + + + Authentication is handled securely by Civic Nexus. Your credentials are never exposed to LeChat or stored locally. + + + + + Try these simple commands to verify everything is working: + + ``` + "What MCP servers are available?" + ``` + + Or test a specific service: + + ``` + "Can you check my recent GitHub pull requests?" + "What's in my Dropbox?" + ``` + + + LeChat chat showing successful tool usage + + + LeChat should now be able to access and interact with your connected services. + + + +## Managing Your MCP Connectors + +### Adding More Tools + +You can add new tools directly in your LeChat conversation: + +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"I need access to PostgreSQL" +"Show me what tools are available to connect" +``` + +LeChat will handle the connection process and guide you through any required authentication steps. + +### Viewing Connected Tools + +To see your currently connected tools: +1. Go to **Intelligence** → **Connectors** in the left sidebar +2. View the list of active connectors +3. You can see connection status and last used time for each + +### Removing Tools + +You can disconnect from specific tools: + + + + Go to **Intelligence → Connectors** in LeChat's left sidebar + + + + 1. Find "Civic Nexus" or the specific tool in your connectors list + 2. Click the **three dots** or **settings** icon next to the connector + 3. Select **"Remove"** or **"Disconnect"** + 4. Confirm the removal when prompted + + + + Visit [nexus.civic.com](https://nexus.civic.com) to revoke service authorizations if you no longer want Civic to have access + + + +### Reset Connection + +If your connector isn't working properly: + + + + 1. Remove the Civic Nexus connector completely + 2. Refresh the LeChat page + 3. Follow the setup steps above to re-add with a fresh MCP URL from nexus.civic.com + + + +## Common Questions + + + + Check your LeChat plan features. MCP connector support may vary by subscription tier. Visit chat.mistral.ai for plan details. + + + + If you encounter authentication issues: + - Make sure you're logged into the correct account for the service + - Check if your account email matches between nexus.civic.com and the service + - Try removing and re-adding the MCP connector with a fresh URL + - Check our [troubleshooting guide](/nexus/troubleshooting) for more solutions + + + + If your nexus.civic.com account uses a different email than your connected services (e.g., work@company.com vs personal@gmail.com), make sure you authenticate with the correct account for each service during the OAuth flow. + + + + Try these steps: + - Refresh the LeChat page + - Remove the connector completely and re-add with a fresh MCP URL + - Check that your browser allows pop-ups for authentication + - Clear browser cache and cookies for chat.mistral.ai + + + +## Two-Minute Verification + +Once connected, test these prompts to make sure everything works: + + + + ``` + "List my GitHub repositories" + "Show me my recent pull requests" + "What issues are assigned to me?" + ``` + + + ``` + "What are the recent messages in #general?" + "List my Slack workspaces" + "Send a test message to myself" + ``` + + + ``` + "What files are in my Dropbox?" + "Show me recently modified documents" + "Search for files containing 'project'" + ``` + + + +## Need Help? + + + Solutions for common LeChat connection issues + + +## Next Steps + +Now that you're connected, explore what you can do: + + + + Add more MCP servers to expand LeChat's capabilities + + + Learn how Nexus keeps your data secure + + + See setup guides for other AI clients + + + Contact us if you need help + + \ No newline at end of file diff --git a/nexus/quickstart/clients/vscode.mdx b/nexus/quickstart/clients/vscode.mdx new file mode 100644 index 00000000..64c47cd7 --- /dev/null +++ b/nexus/quickstart/clients/vscode.mdx @@ -0,0 +1,240 @@ +--- +title: VS Code Setup +description: Connect VS Code to Civic Nexus with MCP extension support in 3 minutes +icon: "code" +--- + +## Prerequisites + + + + Download and install VS Code (free) + + + Required for the Hub Bridge - check with `node --version` + + + +## Setup Options + +VS Code now supports both local Hub Bridge and direct remote HTTP endpoints. + +### Option 1: Remote HTTP Endpoint (Direct Connection) + + + + 1. Sign in to [nexus.civic.com](https://nexus.civic.com) + 2. Select the MCP servers you want to use + 3. Copy the MCP URL: `https://nexus.civic.com/hub/mcp` + + + + 1. Open VS Code Settings (**File → Preferences → Settings**) + 2. Search for "MCP" + 3. In the **MCP Servers** section, click **Add Server** + 4. Configure: + - **Name**: Civic Nexus + - **Type**: http + - **URL**: `https://nexus.civic.com/hub/mcp` + 5. Save the configuration + + + + In VS Code Settings, search for "MCP" and enable the required MCP extension options + + + + Try these commands to verify: "What MCP servers are available?" + + + +### Option 2: Hub Bridge (Local Connection) + + + + Use the one-click install button below: + + +
+ 📦 Add to VS Code (Hub Bridge) +
+ + + + + When VS Code opens, click "Install" to add the Civic Nexus MCP server + + + + In VS Code Settings, search for "MCP" and enable the required MCP extension options + + + + The first time you use any MCP command, the Hub Bridge will: + - Automatically download and install itself + - Handle authentication directly in the chat interface + - Let you select which tools to connect from nexus.civic.com + + + +## Test Your Connection + +Try these prompts in VS Code's chat/AI features: + +``` +"What MCP servers are available?" +"Show me my connected tools" +"Help me set up GitHub integration" +``` + +## Manual Setup (Alternative) + +If the one-click install doesn't work, add Civic Nexus manually: + +### Method 1: Via VS Code Settings (Recommended) + + + + Go to **File → Preferences → Settings**, then search for "MCP" + + + + 1. Look for **MCP Servers** section in settings + 2. Click **Add Server** or **+** + 3. Configure the server: + - **Name**: Civic Nexus + - **Type**: stdio + - **Command**: npx -y @civic/hub-bridge + 4. Save the configuration + + + + Enable MCP features and test with: "What MCP servers are available?" + + + +### Method 2: Via Configuration File + + + + Create a file called **`.mcp.json`** in your workspace root directory + + + + Add the following content: + ```json + { + "servers": { + "civic-nexus": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@civic/hub-bridge"] + } + } + } + ``` + + + + Save the file and restart VS Code. The MCP server will be automatically detected. + + + + Test with: "What MCP servers are available?" + + + +## Troubleshooting + + +Make sure VS Code is installed and try copying this URL manually: +``` +vscode:mcp/install?%7B%22name%22%3A%22Civic%20Nexus%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40civic%2Fhub-bridge%22%5D%7D +``` + + + +Install Node.js 18 or later from [nodejs.org](https://nodejs.org) and restart VS Code. + + + +Make sure you have the MCP extension installed. Some VS Code versions require additional extensions for MCP support. + + + +The Hub Bridge should handle authentication in the chat. If it doesn't: +1. Restart VS Code +2. Make sure you're trying to use a tool that requires authentication +3. Try running the Hub Bridge manually: `npx -y @civic/hub-bridge` + + +## Managing Your Tools + +### Adding More Tools + +You can add new tools directly in your VS Code chat: + +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"I need access to PostgreSQL" +"Show me what tools are available to connect" +``` + +VS Code will handle the connection process and guide you through any required authentication steps. + +### Removing Tools + +You can disconnect from specific tools directly in chat: + +``` +"Disconnect from Slack" +"Remove GitHub from my tools" +"What tools do I currently have connected?" +"Stop my access to Dropbox" +``` + +### Removing the MCP Server + +To remove Civic Nexus completely: + +**Via Settings:** + + + Go to **File → Preferences → Settings** and search for "MCP" + + + 1. Find "Civic Nexus" in your MCP servers list + 2. Click the **Delete** or **Remove** button next to it + + + +**Via Configuration File:** + + + Open your **`.mcp.json`** file in the workspace root + + + Delete the `"civic-nexus"` entry from the `servers` object + + + Save the file and restart VS Code + + + +## Resources + + + + Detailed Hub Bridge setup for VS Code + + + Technical details about VS Code MCP support + + + Common VS Code connection issues + + + Join our developer community for setup assistance + + diff --git a/nexus/quickstart/clients/windsurf.mdx b/nexus/quickstart/clients/windsurf.mdx new file mode 100644 index 00000000..83f13fdf --- /dev/null +++ b/nexus/quickstart/clients/windsurf.mdx @@ -0,0 +1,34 @@ +--- +title: Windsurf Setup +description: Connect Windsurf AI IDE to Civic Nexus +icon: "wind" +--- + + + Windsurf setup instructions coming soon... + + +## Overview + +Windsurf (Codeium's AI IDE) requires the Hub Bridge method for connecting to Civic Nexus MCP servers. + +## Coming Soon + +Complete setup instructions for Windsurf configuration and troubleshooting are being prepared. + +## Resources + + + + Essential Hub Bridge setup for Windsurf + + + Windsurf MCP support details + + + Common Windsurf connection issues + + + Join our developer community for Windsurf setup help + + diff --git a/nexus/quickstart/hub-bridge.mdx b/nexus/quickstart/hub-bridge.mdx new file mode 100644 index 00000000..15cd9d71 --- /dev/null +++ b/nexus/quickstart/hub-bridge.mdx @@ -0,0 +1,301 @@ +--- +title: Hub Bridge Setup +description: Use Hub Bridge when your client doesn't support Remote URL connections +icon: "bridge" +--- + +## What is Hub Bridge? + +Hub Bridge is a local proxy that connects clients (like Cursor, VS Code, JetBrains) to Civic Nexus. Your client thinks it's talking to a local MCP server, but the bridge handles authentication and forwards requests to your selected Nexus servers. + +**npm package:** [`@civic/hub-bridge`](https://www.npmjs.com/package/@civic/hub-bridge) + + +**Use Hub Bridge when:** Your client only supports local/stdio MCP servers and doesn't have remote URL options. + + +## Check Client Compatibility First + +Before setting up Hub Bridge, check if your client supports Remote URL connections instead: + + + See which clients support Remote URL vs Hub Bridge - Remote URL is simpler if your client supports it + + +**Use Hub Bridge for:** Cursor, VS Code, JetBrains IDEs, Windsurf, Claude Code, and other clients that only support local/stdio MCP servers. + +## Setup: Edit Your Client's Configuration + +Most clients that require Hub Bridge use a JSON configuration file. Here's how to set it up: + +## Prerequisites + + +Make sure you have these before starting: + + +- **Node.js 18 or higher** - Check with `node --version` +- **Terminal access** - macOS/Linux Terminal, Windows PowerShell, or Command Prompt +- **Internet connection** - For initial download and authentication +- **Default browser** - Bridge opens browser for one-time authentication + +### Install Node.js (if needed) + + + + ```bash + # Using Homebrew (recommended) + brew install node + + # Or download from nodejs.org + ``` + + + ```powershell + # Using winget + winget install OpenJS.NodeJS + + # Or download from nodejs.org + ``` + + + ```bash + # Ubuntu/Debian + sudo apt update && sudo apt install nodejs npm + + # Or use NodeSource repository for latest version + ``` + + + + +## Configuration by Client + +Each client has its own configuration format and file location. Choose your client below: + + + + **File Location:** `.cursor/mcp.json` in your project root + + **Configuration:** + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + **Alternative:** Use Cursor Settings → Features → MCP → Add New MCP Server + + + + **File Location:** `.mcp.json` in your workspace root + + **Configuration:** + ```json + { + "servers": { + "civic-nexus": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + **Alternative:** Use File → Preferences → Settings → search "MCP" + + + + **File Location:** Check your IDE's MCP plugin documentation for config file location + + **Configuration:** Most JetBrains IDEs use a similar format: + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + **Setup:** Add via IDE Settings → Plugins → MCP configuration + + + + **General Format:** Look for MCP server configuration in your client settings + + **Common patterns:** + - **Command:** `npx` + - **Arguments:** `["-y", "@civic/hub-bridge@latest"]` + - **Type:** `stdio` (if required) + - **Name:** `Civic Nexus` or `civic-nexus` + + The Hub Bridge will work with any client that supports local MCP servers via stdio. + + + + +**All these configurations use the Hub Bridge** - your client runs `npx -y @civic/hub-bridge` locally, and the bridge handles connecting to Civic Nexus servers. + + +### Step 2: First Run Authentication + +When you first use an MCP command, the bridge will automatically: + + + + 1. Create your Civic account (Google, GitHub, etc.) + 2. During account creation, select which MCP servers you want to connect (GitHub, Slack, etc.) + + + Bridge downloads itself (happens once, ~30 seconds) + + + Your default browser opens to nexus.civic.com for authentication + + + Bridge is now configured and your client can access your selected tools + + + When you first use each specific tool, you'll authorize access to that app (e.g., GitHub OAuth, Slack workspace permission) + + + +### Managing Your Server Selection + +You can modify which servers you have access to in two ways: + +**Option 1: In Chat** +``` +"Connect me to GitHub" +"Add Slack to my available tools" +"Show me what tools are available to connect" +"Remove Dropbox from my tools" +``` + +**Option 2: On nexus.civic.com** +Visit the website to add or remove servers from your account selection. + +### Step 3: Test Connection + +Try these commands in your AI client: + +``` +"What MCP servers are available?" +"List my GitHub repositories" +"Show me recent Slack messages" +``` + + +## Troubleshooting + +### Common Issues + + + + **Problem:** `npx: command not found` or `'npx' is not recognized` + + **Solution:** + - Install Node.js 18+ from nodejs.org + - Restart your terminal/IDE after installation + - Verify with `node --version` and `npm --version` + + + + **Problem:** Authentication browser window doesn't appear + + **Solution:** + - Corporate firewall may be blocking - try from personal network + - Manually visit the auth URL shown in terminal output + - Check if default browser is set correctly + - Try running from regular terminal instead of IDE terminal + + + + **Problem:** Bridge connects but client doesn't see any MCP tools + + **Solution:** + - Restart your client completely after bridge setup + - Check that you selected servers during authentication + - Try using the bridge again to see if it works + - Some clients need manual restart of MCP features + + + + **Problem:** Repeated auth prompts or 401 errors + + **Solution:** + - Try reinstalling: remove the MCP server from your client and add it back + - Check system time is accurate (OAuth is time-sensitive) + - Disable VPN temporarily during initial setup + - Join our developer community if issue persists + + + + **Problem:** Bridge responses are slow or timeout + + **Solution:** + - Check internet connection stability + - Corporate proxy may be interfering - try personal network + - Some MCP operations are inherently slower (large file operations) + - Bridge caches auth tokens to minimize delays + + + +### Corporate Network Considerations + +If you're on a corporate network: + +- **Proxy servers** may interfere with authentication - whitelist `nexus.civic.com` and `*.civic.com` +- **Firewall rules** might block npm/npx - work with IT to allow Node.js tools +- **Certificate issues** - corporate TLS inspection can cause SSL errors +- **Alternative:** Try initial setup from personal network, then bridge should work on corporate network + +### Getting More Help + + + + Note any error messages you see when trying to use MCP commands + + + Note your OS, Node version (`node --version`), and client type + + + Include the above info when contacting support for faster resolution + + + + + Contact our support team with your specific setup details + + +## How Hub Bridge Works + +The Hub Bridge follows a modular architecture with clear separation of concerns: + +### Core Components + +- **Bridge Core**: Connects stdio and HTTP/SSE transports, forwards messages between client and server +- **Auth Provider**: Handles OAuth client interface for Civic authentication with PKCE flow +- **Callback Server**: Creates local HTTP server for OAuth redirects with dynamic port selection +- **Token Store**: Manages secure storage of authentication tokens with file system persistence +- **OIDC Configuration**: Fetches OpenID Connect configuration from discovery endpoints + +### Authentication Flow + +1. **Civic Authentication**: Automatically initiated when bridge starts using PKCE for security +2. **Service-Specific Authentication**: Intercepts auth URL errors, opens browser for user authorization +3. **Token Management**: Stores tokens locally for subsequent uses, handles refresh automatically + +### Environment Variables + +The Hub Bridge may support environment variables for configuration, but refer to the [official package documentation](https://www.npmjs.com/package/@civic/hub-bridge) for the most current and accurate list of supported options. + diff --git a/nexus/quickstart/index.mdx b/nexus/quickstart/index.mdx new file mode 100644 index 00000000..d99572ac --- /dev/null +++ b/nexus/quickstart/index.mdx @@ -0,0 +1,165 @@ +--- +title: Get Started +description: Connect your AI assistant to Nexus in 2 minutes +icon: "bolt" +--- + +## Quick Start: Try It Now (2 Minutes) + + + Nexus built-in chat interface + + +### Easiest Way: Test Directly in Nexus + + + + **[Sign up](https://nexus.civic.com)** and browse dozens of available MCP servers + + + **No setup required** - start using tools immediately in our built-in chat interface + + + Ask: **"Connect me to GitHub"**, **"Check my Slack messages"**, etc. - authorize tools as needed + + + + + **Fastest way to get started** - No client setup, no configuration, just sign up and start chatting + + +### Optional: Connect External AI Clients + +Once you've tried it in Nexus chat, connect your favorite AI assistant for convenience: + +## Choose Your AI Client + +### Primary Clients (Recommended) + + + + **Available Now** - Direct connector (2 mins) + + + **Available Now** - Web interface (2 mins) + + + **Available Now** - Direct connector (2 mins) + + + + +**Why these clients?** Claude and Mistral LeChat offer the simplest setup with direct MCP connector support - no technical configuration required. + + +### Development Tools & Advanced Clients + + + Setup guides for Cursor, VS Code, JetBrains IDEs, and other development tools + + +### All Other Supported Clients + + + + AI code editor • 3 mins + + + Popular IDE • 3 mins + + + IntelliJ, PyCharm • 5 mins + + + Codeium AI IDE • 5 mins + + + Block's dev agent • 5 mins + + + See all supported clients + + + +## Two Setup Methods + +### Direct Connector (Recommended) +**For:** Claude Desktop, Claude.ai, Mistral LeChat + +The simplest method for primary AI assistants: + +1. Visit [nexus.civic.com](https://nexus.civic.com) and select tools +2. Copy the MCP URL: `https://nexus.civic.com/hub/mcp` +3. Add as a custom connector in your AI client settings + +**Why this is easier:** +- ✅ No technical configuration required +- ✅ No local software installation +- ✅ Works across all devices +- ✅ Automatic updates and maintenance + +### Hub Bridge (Development Tools) +**For:** Cursor, VS Code, JetBrains, Windsurf, CLI tools + +Development tools use the Hub Bridge - a local proxy that handles authentication: + + + **Complete setup instructions** for all development tools including Cursor, VS Code, JetBrains IDEs, and command-line clients + + +**When to use this method:** +- Your client only supports local/stdio MCP servers +- You need project-level configuration control +- You're working with development environments +- Your client doesn't support remote MCP URLs + + +**Start with primary clients first** - Claude and Mistral LeChat offer the simplest setup experience. Add development tools later if needed. + + +## What You Can Do + +Once connected, ask your AI assistant to use your tools: + +**Development workflows:** +- "Check my open GitHub pull requests" +- "Create a new issue for the login bug" +- "Show me recent commits in the feature branch" + +**Team workflows:** +- "Summarize today's Slack messages in #general" +- "Send a message to the team about deployment" +- "What files did I upload to Dropbox this week?" +- "Create a new page in our Notion workspace" + +## Next Step: Organize with Toolkits + +Instead of giving your AI access to all tools at once (which can confuse it), create focused tool groups for specific workflows: + + + + **Google Analytics + Notion + Slack** for data analysis and reporting workflows + + + **GitHub + PostgreSQL + Notion** for investigating and documenting issues + + + + + **Improve AI performance** - Create focused tool groups that help your AI choose the right tools for each task + + +## Need Help? + + + + Full matrix of which clients use which connection method + + + Common setup issues and solutions + + diff --git a/nexus/quickstart/nexus-chat.mdx b/nexus/quickstart/nexus-chat.mdx new file mode 100644 index 00000000..c4a8e0ee --- /dev/null +++ b/nexus/quickstart/nexus-chat.mdx @@ -0,0 +1,218 @@ +--- +title: Nexus Chat +description: Use Civic Nexus tools directly in our built-in chat interface - no setup required +icon: "sparkles" +--- + + + **Fastest way to get started** - No client setup, no configuration. Just sign up and start using hundreds of tools immediately. + + +## What is Nexus Chat? + +Nexus Chat is the built-in chat interface at [nexus.civic.com](https://nexus.civic.com) that lets you: +- Test all MCP servers instantly without any setup +- Connect to tools with simple conversational commands +- Handle authentication flows seamlessly +- Start working with your tools in under 2 minutes + + + Nexus Chat interface + + +## Get Started in 2 Minutes + + + + Create your free account at [nexus.civic.com](https://nexus.civic.com) + + Civic Nexus signup page + + + + Once logged in, click the **Chat** button to open the built-in interface + + + No downloads, no configuration files, no API keys needed + + + + + Simply ask for what you need: + - "Connect me to GitHub" + - "Add Slack to my tools" + - "I need access to Dropbox" + - "Show me available MCP servers" + + + Tool connection in Nexus Chat + + + + + When connecting a new service: + 1. Nexus Chat will provide an authorization link + 2. Click the link to authenticate with the service + 3. Return to chat when complete + 4. Start using your connected tools immediately + + + Authorization prompt in Nexus Chat + + + + +## What You Can Do + +Once connected, use natural language to work with your tools: + + + + ``` + "List my GitHub repositories" + "Create an issue for the login bug" + "Show me open pull requests" + "Check the CI status of my latest commit" + ``` + + + ``` + "What are the latest messages in #general?" + "Send a Slack message to the team" + "Show me unread emails" + "Draft a response to the latest email" + ``` + + + ``` + "What files are in my Dropbox?" + "Search for the quarterly report" + "Create a new document called 'Meeting Notes'" + "Show me recently modified files" + ``` + + + ``` + "Add these contacts to my ActiveCampaign list" + "Show me the latest email campaign stats" + "Create a new tag for conference attendees" + "Update the CRM with these leads" + ``` + + + +## Managing Your Tools + +### View Connected Tools + +Ask Nexus Chat to show your current setup: +``` +"What tools do I have connected?" +"Show me my available MCP servers" +"List my authorized services" +``` + +### Add More Tools + +Connect new services anytime: +``` +"Connect me to PostgreSQL" +"Add Notion to my tools" +"I need access to Linear" +"Show me all available MCP servers" +``` + +### Remove Tools + +Disconnect services you no longer need: +``` +"Disconnect from Slack" +"Remove my GitHub authorization" +"Revoke access to Dropbox" +``` + +## Why Start with Nexus Chat? + + + + No installation, no configuration files, no technical knowledge required + + + Try all MCP servers and features before setting up external clients + + + Start using tools in under 2 minutes - just sign up and chat + + + Works on any device with a web browser - desktop, tablet, or mobile + + + +## Optional: Connect External Clients + +After testing in Nexus Chat, you can optionally connect external AI clients for convenience: + + + + Desktop app integration + + + Web interface integration + + + Mistral's AI assistant + + + + +**Nexus Chat is always available** - Even if you connect external clients, you can always return to Nexus Chat for testing new tools or troubleshooting. + + +## Security & Privacy + + +All conversations and tool interactions in Nexus Chat are: +- **Encrypted** in transit and at rest +- **Private** to your account only +- **Secure** with OAuth2 authentication for external services +- **Revocable** at any time through your account settings + + +## Get Started Now + + + **Click here to start** - Sign up and begin using hundreds of tools in our built-in chat interface + + +## Need Help? + + + + Step-by-step setup instructions + + + Browse all MCP servers you can connect + + + Common issues and solutions + + + Join our developer community + + \ No newline at end of file diff --git a/nexus/reference/authorizations.mdx b/nexus/reference/authorizations.mdx new file mode 100644 index 00000000..8c6312db --- /dev/null +++ b/nexus/reference/authorizations.mdx @@ -0,0 +1,177 @@ +--- +title: Managing Authorizations +description: Understand and control access to your connected services and data +icon: "key" +--- + +## What are Authorizations? + +An authorization is the permission you give Civic Nexus to access your tools and services on your behalf. When you connect a service like GitHub, Slack, or Notion to Nexus, you're creating an authorization that allows your AI assistants to interact with that service using your account. + + +**You're always in control** - Once you've given access to your tools, you can always revoke them instantly. Authorizations are not permanent and can be managed at any time. + + +## How Authorizations Work + +When you first connect a service to Nexus: + +1. **You grant permission** - You authorize Nexus to access specific data from the service +2. **Secure token storage** - Nexus securely stores your access tokens with encryption +3. **AI assistant access** - Your AI can now use that service through MCP tools +4. **Ongoing control** - You maintain full control to revoke access anytime + + + Dashboard showing connected apps with revoke access buttons + + +## Managing Your Authorizations + +### Full Control Over Access + +- ✅ **View all connections** - See every service you've authorized +- ✅ **Instant revocation** - Remove access to any service immediately +- ✅ **Immediate effect** - Changes apply across all your AI assistants instantly + +### When to Revoke Access + +You might want to revoke authorizations when: + +- **No longer using a service** - Clean up unused connections +- **Security concerns** - Remove access if you suspect any issues +- **Account changes** - When switching accounts or roles +- **Testing purposes** - Temporarily disable specific integrations +- **Privacy preferences** - Limit AI assistant access to certain data + +## How to Revoke Authorizations + + + + Go to [nexus.civic.com](https://nexus.civic.com) and sign in to your account + + + + Navigate to your account settings or connected services section + + + + Find the service you want to disconnect and click the revoke or disconnect option + + + + Confirm that you want to remove access to this service + + + + +**Immediate Effect**: When you revoke access to a service, it will immediately stop working across all your AI assistants. Any ongoing conversations or tasks using that service will be interrupted. + + +## Authorization Scope and Permissions + +### What You Authorize + +When you connect a service, you typically grant access to: + +- **Read your data** - View files, messages, repositories, etc. +- **Create content** - Add new items, send messages, create files +- **Update existing items** - Edit documents, update records, modify settings +- **Delete items** - Remove content when explicitly requested + +### What You DON'T Authorize + +Nexus and your AI assistants cannot: + +- **Access other accounts** - Only your explicitly connected accounts +- **Exceed your permissions** - AI has the same limits as your user account +- **Access unrelated services** - Only services you've specifically connected +- **Persist beyond revocation** - Access stops immediately when revoked + +## Security and Privacy + +### Protected Information + +Your authorization data is protected through: + +- 🔒 **Encrypted storage** - All tokens encrypted at rest +- 🔐 **Secure transmission** - TLS encryption for all communications +- 🛡️ **Access controls** - Only you can view or modify your authorizations +- ⏰ **Automatic refresh** - Tokens refreshed securely without your intervention + +### Minimal Permissions + +When you connect a service to Nexus, we only ask for the specific permissions we actually need. We request the minimum access required for AI assistants to work with your tools, and nothing more. + +This approach helps protect your data by ensuring Nexus never requests unnecessary permissions to access or modify your accounts. + +## Best Practices + + + + **Monthly review recommended:** + - Check which services are still connected + - Remove authorizations for unused services + - Verify all connections are still needed + - Clean up old or forgotten integrations + + + + **Only connect what you need:** + - Start with essential services only + - Add more connections as needed + - Remove authorizations when projects end + - Keep your authorization list minimal and relevant + + + + **Protect your authorizations:** + - Use strong passwords for connected accounts + - Enable 2FA on all connected services + - Monitor for unusual activity + - Revoke access immediately if concerned + + + +## Troubleshooting Authorization Issues + + + + **Problem:** Can't authorize a new service + + **Solutions:** + - Ensure you're signed into the correct account for the service + - Check if the service is temporarily unavailable + - Clear browser cookies and try again + - Join our developer community if the issue persists + + + + **Problem:** Connected service isn't responding to AI requests + + **Solutions:** + - Wait a few minutes for authorization to propagate + - Try disconnecting and reconnecting the service + - Check if your account permissions changed + - Verify the service is online and accessible + + + + **Problem:** Unable to disconnect a service + + **Solutions:** + - Refresh the page and try again + - Clear browser cache and cookies + - Try from a different browser or device + - Join our developer community for assistance + + + +## Need Help? + + + Having trouble with authorizations? Join our developer community for assistance with connecting or disconnecting services. + diff --git a/nexus/reference/client-compatibility.mdx b/nexus/reference/client-compatibility.mdx new file mode 100644 index 00000000..ff2e59fb --- /dev/null +++ b/nexus/reference/client-compatibility.mdx @@ -0,0 +1,297 @@ +--- +title: Client Compatibility +description: Complete guide to connecting Nexus with your AI assistant or development tool +icon: "table" +--- + +## Compatibility Overview + +Civic Nexus works with all major AI assistants and development tools. The setup method depends on whether your client supports remote MCP URLs or requires local configuration. + + + Visit **nexus.civic.com** to select your tools and get your connection details + + + +**Quick rule**: If your client settings mention "remote MCP URL" or "HTTP connector", use **Remote URL**. If they only show "local MCP server" or "stdio/command", use **JSON Configuration**. + + +## Client Compatibility Matrix + +| Client | Platform | Connection | Setup Time | Popularity | Guide | +|--------|----------|------------|------------|------------|-------| +| **Claude Desktop** | Desktop | Remote URL | 2 mins | 🔥 Most Popular | [Setup](/nexus/quickstart/clients/claude-desktop) | +| **Claude.ai** | Web | Remote URL | 2 mins | 🔥 Very Popular | [Setup](/nexus/quickstart/clients/claude-web) | +| **Cursor** | Desktop | Hub Bridge | 3 mins | 🔥 Very Popular | [Setup](/nexus/quickstart/clients/cursor) | +| **VS Code** | Desktop | Hub Bridge | 3 mins | 🔥 Popular | [Setup](/nexus/quickstart/clients/vscode) | +| **Goose** | CLI | Remote URL | 2 mins | 📈 Growing | [Setup](/nexus/quickstart/clients/goose) | +| **JetBrains IDEs** | Desktop | Hub Bridge | 2 mins | 💼 Enterprise | [Setup](/nexus/quickstart/clients/jetbrains) | +| **Windsurf** | Desktop | Hub Bridge | 2 mins | 🆕 New | [Setup](/nexus/quickstart/clients/windsurf) | +| **Claude Code** | CLI | Hub Bridge | 2 mins | 💻 Developer | [Setup](/nexus/quickstart/clients/claude-code) | +| **Gemini CLI** | CLI | Hub Bridge | 2 mins | 🚀 Google | [Setup](/nexus/quickstart/clients/gemini) | + + +**ChatGPT Support**: ChatGPT does not currently support MCP connectors and cannot connect to Civic Nexus. We're monitoring ChatGPT's roadmap and will add support when OpenAI releases MCP connector functionality. For now, we recommend **Claude Desktop** or **Claude.ai** for the best experience. + + +## Connection Methods + +### Remote URL (Most Popular) + +**How it works:** Copy the MCP URL from [nexus.civic.com](https://nexus.civic.com) and paste it into your client's settings. + +**Clients that support this:** +- **Claude Desktop** - Most popular choice +- **Claude.ai (Web)** - No installation required +- **Goose** - Developer CLI tool +- Any client with "remote MCP URL" or "HTTP connector" options + +**Pros:** +- ✅ Fastest setup (2 minutes) +- ✅ No local software needed +- ✅ Automatic updates +- ✅ Works across devices +- ✅ Most reliable connection + +**Setup steps:** +1. Visit **[nexus.civic.com](https://nexus.civic.com)** and select your tools +2. Copy the MCP URL +3. Paste into your client's MCP settings + + + Complete walkthrough for the most popular setup method + + +### JSON Configuration (Development Tools) + +**How it works:** Edit your client's JSON configuration file to add the Hub Bridge, which connects to Civic Nexus servers. + +**Clients that need this:** +- **Development Tools**: Cursor, VS Code, JetBrains IDEs +- **CLI Tools**: Windsurf, Claude Code, Gemini CLI +- Any client with only "local MCP server" or "stdio" options + +**Pros:** +- ✅ Works with any MCP client +- ✅ Local configuration control +- ✅ Transparent setup process + +**Requirements:** +- Node.js 18+ installed +- Access to edit configuration files + +**Common Configuration Formats:** + + + + **File:** `.cursor/mcp.json` in project root + ```json + { + "mcpServers": { + "civic-nexus": { + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + + **File:** `.mcp.json` in workspace root + ```json + { + "servers": { + "civic-nexus": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@civic/hub-bridge@latest"] + } + } + } + ``` + + + **General pattern:** Most clients use similar formats with: + - **Command:** `npx` + - **Arguments:** `["-y", "@civic/hub-bridge@latest"]` + - **Type:** `stdio` (if required) + + + +**Setup steps:** +1. **Create account:** Visit **[nexus.civic.com](https://nexus.civic.com)** and select your tools +2. **Edit config file:** Add the Hub Bridge configuration to your client's JSON file +3. **Restart client:** The bridge handles authentication automatically + + + Detailed configuration examples for all clients + + +## Which Method Should I Use? + +### Start with Remote URL (If Supported) +If your client supports it, Remote URL is the better choice: +- ⚡ **Faster setup** - Just copy/paste a URL +- 🚫 **No Node.js requirement** - Works immediately +- 🔄 **No local software to maintain** - Always up to date +- 🌐 **Works across devices** - Same URL everywhere + +### Use JSON Configuration When Required +Use JSON configuration for: +- 💻 **Development tools** - IDEs like Cursor, VS Code, JetBrains +- 🛠️ **CLI tools** - Command line interfaces and scripts +- 📝 **Local MCP clients** - Tools that only support stdio/local servers +- 🏢 **Corporate environments** - When remote URLs are blocked + + +**Not sure which method?** Check your client's settings - if you see "remote MCP URL" options, use Remote URL. If you only see "local MCP server" or need to configure a command, use JSON configuration. + + +## Common Setup Scenarios + +### 🆕 First-Time Users +**Recommendation:** Start with **Claude Desktop** (Remote URL) +- ✅ Easiest 2-minute setup process +- ✅ Most reliable connection method +- ✅ Best documentation and community support +- ✅ Perfect for learning how Civic Nexus works + + + Get up and running in 2 minutes with the most popular setup + + +### 👩‍💻 Developers +**Popular development workflows:** + + + + **JSON Config** - Perfect for coding workflows and project integration + + + **JSON Config** - AI-first development experience with code assistance + + + +**Pro tip:** Many developers use **Claude Desktop** for quick queries alongside their IDE setup. + +### 👥 Teams & Organizations +**Team-friendly options:** + +- **🌐 Claude.ai (Web)**: No installation required, works from any browser +- **🖥️ Claude Desktop**: Consistent experience across all team members +- **🔗 Multiple clients**: Each team member can use their preferred client with the same [nexus.civic.com](https://nexus.civic.com) account + +### 🏢 Enterprise Users +**Enterprise considerations:** +- **JetBrains IDEs**: Popular in enterprise development environments +- **JSON Configuration**: Better for IT management and deployment +- **Corporate firewalls**: JSON config may work better with strict network policies + +## Troubleshooting Common Issues + + + + **Problem:** Your client only supports local/stdio MCP servers + + **Solution:** Use JSON configuration instead of Remote URL: + 1. Find your client in our [setup guides](/nexus/quickstart) + 2. Follow the JSON configuration instructions + 3. Your client will use the Hub Bridge to connect to Civic Nexus + + + + **Problem:** JSON configuration requires Node.js but it's not installed + + **Solution:** + - Install Node.js 18+ from [nodejs.org](https://nodejs.org) + - Or use a package manager: `brew install node` (macOS) or `winget install OpenJS.NodeJS` (Windows) + - Restart your terminal/IDE after installation + - Verify with `node --version` + + + + **Remote URL issues:** + - Check internet connection and firewall settings + - Try visiting [nexus.civic.com](https://nexus.civic.com) directly in browser + - Corporate firewalls may block the connection + + **JSON configuration issues:** + - Ensure Node.js is properly installed (`node --version`) + - Try restarting your client completely + - Check that the JSON syntax is correct (no trailing commas, proper quotes) + + + + **Problem:** OAuth authentication not working + + **Solutions:** + - Clear browser cache and try again + - Use incognito/private browsing mode + - Check if your organization blocks OAuth flows + - Try from a different network (personal vs corporate) + - Make sure you're creating an account at [nexus.civic.com](https://nexus.civic.com) first + + + + **Problem:** Connected but can't see/use tools + + **Solutions:** + - Make sure you selected tools during account creation at [nexus.civic.com](https://nexus.civic.com) + - Try asking: `"What tools do I have available?"` or `"What MCP servers are connected?"` + - Restart your client completely after setup + - For JSON config: verify the configuration file syntax is correct + + + + + Join our developer community with your specific client and error details + + +## Getting Help & Next Steps + + + + Step-by-step setup for your specific AI client + + + See all the MCP servers and tools you can connect + + + Get personalized help with your setup + + + +### Popular Next Steps After Setup + + + + Visit **[nexus.civic.com](https://nexus.civic.com)** to browse and select from dozens of available MCP servers + + + Try commands like: `"What tools are available?"` or `"Check my GitHub repositories"` + + + Use chat commands: `"Connect me to Slack"` or `"Add Dropbox to my tools"` + + + See our [server reference](/nexus/reference/servers) for what each tool can do + + + +## Technical Details + + +**Protocol:** HTTP/HTTPS MCP over REST API +**Authentication:** OAuth2 with PKCE flow +**Token Management:** Automatic refresh, secure storage +**Transport:** JSON-RPC over HTTP +**Benefits:** Cloud-native, automatically updated, cross-platform + + + +**Protocol:** stdio MCP (local process communication) +**Authentication:** Proxied OAuth2 through local server +**Token Management:** Local encrypted storage +**Transport:** JSON-RPC over stdin/stdout +**Benefits:** Works with any MCP client, local control + diff --git a/nexus/reference/security.mdx b/nexus/reference/security.mdx new file mode 100644 index 00000000..dd01830f --- /dev/null +++ b/nexus/reference/security.mdx @@ -0,0 +1,155 @@ +--- +title: Security & Token Management +description: How Civic Nexus protects your data and manages authentication +icon: "shield-check" +--- + + + Your data security is our top priority. Civic Nexus handles all authentication and token management so you don't have to. + + +## How We Protect Your Data + +**🔒 Token Management** +- Civic securely manages all access tokens and automatically refreshes them +- Your tokens are encrypted and stored in secure, stringent infrastructure +- No tokens are ever exposed to AI clients or other users + +**⚡ Authorization Control** +- You maintain full control over your app authorizations +- Revoke access to any connected service at any time +- Authorization changes take effect immediately across all your AI tools + + + **Complete guide** - Learn what authorizations are, how to revoke access, and manage your connected services + + +**🛡️ Data Access** +- Apps only access data you explicitly authorize +- AI assistants work through secure, encrypted connections +- Conversation history stored to improve the product with full encryption and security controls + +## Common Security Questions + + + + + Your access tokens are encrypted and stored in secure, stringent infrastructure. They're never exposed to AI clients, other users, or external systems beyond the authorized app connections you've approved. + + + + Civic Nexus automatically handles token refresh for all your connected services. You'll never need to manually re-authenticate or deal with expired tokens - it all happens seamlessly in the background. + + + + AI assistants can only access data from apps you've explicitly connected and authorized. The access follows the same permissions you have in those apps - no more, no less. You control which apps to connect and can disconnect them anytime. + + + + Yes, all data transmission between your AI assistants, Civic Nexus, and your connected apps uses stringent TLS encryption. Your data is protected at every step of the workflow. + + + + We actively review and manage all MCP servers in our directory. Every server undergoes security review before being added, and we continuously monitor for vulnerabilities. Updates are only deployed after thorough security assessment to ensure your data remains protected. + + + +## Security Features + +### Infrastructure +- Data encryption at rest and in transit +- Regular security audits and penetration testing +- 24/7 monitoring and incident response +- Advanced threat detection and response + +### Zero Trust Architecture +- Every request is authenticated and authorized +- Principle of least privilege access +- Session-based security controls +- Automatic token rotation + +### Privacy by Design +- Conversations stored for 1 day to improve the product, then automatically deleted +- User-controlled data access and deletion +- Transparent data handling practices +- All stored data encrypted at rest and in transit +- Privacy-focused design principles throughout the platform + +### Authentication Methods +- OAuth2 for secure app authorization +- API key management for supported services +- Multi-factor authentication support +- Single sign-on (SSO) integration + +### MCP Server Security Review + +**Proactive Server Management** +- All MCP servers undergo rigorous security review before being added to our directory +- Continuous monitoring of server code and dependencies for security vulnerabilities +- Regular updates only deployed after thorough security assessment +- Immediate response to reported security issues with affected servers + +**Our Review Process** +- Source code analysis for security vulnerabilities and best practices +- Dependency scanning for known security issues +- Authentication and authorization mechanism validation +- Data handling and privacy compliance verification + +## Security Best Practices + + +Follow these recommendations to maximize your security when using Civic Nexus: + + +### For Organizations +- Regularly review connected applications +- Use SSO where available +- Monitor access logs and activity +- Implement least-privilege access policies + +### For Individual Users +- Only connect apps you actively use +- Review and revoke unused connections monthly +- Use strong authentication methods +- Keep your AI client software updated + +## Incident Response + +If you suspect a security issue: + + + + Revoke access to any affected services through your Civic Nexus dashboard + + + Join our developer community on Slack to report security issues + + + Check your connected apps for any unusual activity + + + +## Compliance & Security Standards + +### Our Approach to Compliance +Civic Nexus is built with security and privacy best practices from the ground up. We follow industry-standard security frameworks and are continuously evaluating formal compliance certifications to meet enterprise requirements. + +### Security Roadmap + + +**Compliance evaluation:** Last updated September 2025 + + +We are actively evaluating compliance certifications to support enterprise customers: +- **GDPR compliance** - Under evaluation to meet European data protection standards +- **CCPA compliance** - Under evaluation for California consumer privacy rights +- **SOC 2 certification** - Under evaluation for enterprise security requirements +- **HIPAA compliance** - Under evaluation for healthcare use cases +- **ISO 27001 certification** - Under evaluation for information security management + +### Enterprise Security +For organizations requiring specific compliance documentation or security assessments, our team works directly with enterprise customers to meet their security requirements. + + +For detailed security documentation, compliance questions, or enterprise security requirements, join our developer community on Slack + diff --git a/nexus/reference/servers.mdx b/nexus/reference/servers.mdx new file mode 100644 index 00000000..ed2cb5d4 --- /dev/null +++ b/nexus/reference/servers.mdx @@ -0,0 +1,69 @@ +# Nexus Servers Overview + +Welcome to the comprehensive directory of Nexus MCP servers. Each server provides specialized tools and capabilities to integrate with external services and platforms, enabling powerful automation and data management workflows. + +## What are Nexus Servers? + +Nexus servers are MCP (Model Context Protocol) compatible integrations that allow AI assistants to interact with external services. Each server acts as a bridge between AI systems and popular platforms, providing: + +- **Structured Tool Access**: Well-defined tools with clear input/output schemas +- **Resource Management**: Direct access to platform data and endpoints +- **Authentication Handling**: Secure credential management for external services +- **Consistent Interface**: Standardized interaction patterns across all platforms + +## Available Servers + +### Currently Documented Servers + +Each server provides multiple tools and capabilities for comprehensive integration. + + + + Marketing automation, email campaigns, contact management, and CRM workflows + + + Repository management, issue tracking, pull requests, and development workflows + + + Team communication, channel management, messaging, and workspace collaboration + + + Database operations, page management, content creation, and knowledge management + + + +### Coming Soon (Additional MCP Servers) + +**🎯 CRM & Marketing** +- HubSpot, LinkedIn, Twitter, Zendesk + +**💻 Development Tools** +- Linear, Figma, Atlassian (Jira/Confluence), Sentry + +**☁️ Cloud & Data** +- AWS API, Dropbox, PostgreSQL, Redshift + +**💬 Communication** +- Slack, Teams, Outlook, Spotify + +**🤖 AI & Automation** +- ElevenLabs, n8n (2 variants), Planning Agent, Claude Code + +*New servers are being documented regularly. Each provides comprehensive tool sets for AI-powered automation.* + +## Getting Started + +1. **Browse Available Servers**: Each server page provides detailed information about capabilities and use cases +2. **Review Tool Documentation**: Understand the specific tools and functions available +3. **Check Authentication Requirements**: Some servers require API keys or OAuth setup +4. **Explore Use Case Examples**: See practical applications and implementation patterns + +## Server Structure + +Each Nexus server follows a consistent structure: +- **Server Metadata**: Name, publisher, version, and classification +- **Tool Catalog**: Complete list of available functions with descriptions +- **Resource Access**: Direct endpoints for data retrieval +- **Authentication**: Required credentials and setup instructions + +This standardized structure ensures consistent integration and usage patterns across all Nexus servers. diff --git a/nexus/reference/servers/activecampaign.mdx b/nexus/reference/servers/activecampaign.mdx new file mode 100644 index 00000000..e6f60e1e --- /dev/null +++ b/nexus/reference/servers/activecampaign.mdx @@ -0,0 +1,321 @@ +--- +title: "ActiveCampaign Server" +description: "Connect to ActiveCampaign's marketing automation platform for CRM, email campaigns, and customer journey management" +icon: "server" +--- + +## Overview + +The ActiveCampaign server provides comprehensive integration with [ActiveCampaign](https://www.activecampaign.com) marketing automation platform, enabling AI assistants to manage customer relationships, email campaigns, and marketing workflows programmatically. + +## Getting Started + + + + Add the ActiveCampaign server to your Nexus environment through the server directory. + + + Start with a simple tool like `get_contact` or `list_contacts` to verify the connection works properly. + + + +## What You Can Do + + + + Create, update, and organize contacts with custom fields and advanced segmentation capabilities + + + Add contacts to automations and manage their journey through sophisticated marketing funnels + + + Create and manage email campaigns, track performance, and analyze engagement metrics + + + Build and maintain targeted email lists for different customer segments and demographics + + + +## Use Cases + + + + - **Lead Segmentation**: Automatically categorize new leads based on behavior, demographics, or engagement patterns + - **Personalized Sequences**: Trigger customized email sequences based on specific customer actions or milestones + - **Data Synchronization**: Keep customer data in sync between ActiveCampaign and other business tools + - **Performance Analytics**: Track campaign effectiveness and optimize marketing spend allocation + + + + - **Lifecycle Tracking**: Monitor customer progression through different stages and automate appropriate communications + - **Engagement Monitoring**: Identify at-risk customers based on email engagement and interaction patterns + - **Re-engagement Campaigns**: Create targeted campaigns to win back inactive subscribers and customers + - **Onboarding Automation**: Guide new customers through structured onboarding sequences + + + + - **Lead Qualification**: Score and qualify leads automatically based on behavior and engagement metrics + - **Sales Routing**: Route qualified prospects to appropriate sales representatives based on territory or expertise + - **Follow-up Automation**: Ensure no leads fall through the cracks with automated nurture sequences + - **Deal Pipeline Management**: Track prospects through the sales funnel with automated status updates + + + +--- + +## Available Tools + +Tool counts may change as the server evolves. See individual categories below for current capabilities. + + + + Core functionality for managing customer and prospect data, including creation, updates, and relationship management. + + **Contact Lifecycle** + + + Create new contacts or update existing ones using email as the unique identifier + + + Retrieve detailed information about a specific contact by their ID + + + Get all contacts with extensive filtering options for segmentation and analysis + + + Find contacts by email address for quick lookups + + + + **Contact Organization** + + + Subscribe a contact to a specific email list for targeted campaigns + + + Unsubscribe a contact from a specific email list + + + Apply tags to contacts for segmentation and automation triggers + + + Remove tags from contacts when criteria no longer apply + + + + **Automation Management** + + + Add a contact to an automation workflow to start their journey through a marketing sequence + + + Stop a contact's participation in an automation sequence + + + + + + Tools for organizing contacts into targeted groups and managing email marketing campaigns. + + **List Management** + + + Create new email lists for organizing contacts by demographics, behavior, or interests + + + Retrieve details about a specific email list including subscriber counts and settings + + + Get all email lists with filtering and pagination for list management + + + Modify existing list properties, settings, and compliance information + + + + **Campaign Operations** + + + Retrieve detailed information about email campaigns including performance metrics + + + Get all tracked links within a campaign for click-through analysis + + + Browse all campaigns with filtering options for reporting and analysis + + + + + + Manage marketing automation workflows and track contact progression through automated sequences. + + + + Get all automation workflows with filtering and ordering options + + + Retrieve specific automation enrollment details for a contact + + + See all automation enrollments for contacts with filtering capabilities + + + + + Automations are the heart of ActiveCampaign. Use these tools to build sophisticated customer journeys that respond to behavior and engagement. + + + + + Advanced contact segmentation and custom data management for personalized marketing. + + **Tag Management** + + + Create new tags for contact categorization and automation triggers + + + Retrieve information about a specific tag including usage statistics + + + Get all available tags with filtering and pagination for tag management + + + + **Custom Field Setup** + + + Add custom data fields to store additional contact information + + + Retrieve details about custom field definitions and options + + + Get all custom fields with filtering for data management + + + Modify custom field properties and validation rules + + + + **Field Value Management** + + + Set custom field values for specific contacts + + + Retrieve custom field values for individual contacts + + + Get all custom field values with filtering options + + + Modify existing custom field values for contacts + + + + **Field Configuration** + + + Associate custom fields with specific email lists + + + Add options for dropdown, radio, or checkbox custom fields + + + Get available options for multi-choice custom fields + + + + + Always create field options after creating fields of type 'dropdown', 'listbox', 'radio', or 'checkbox' for proper functionality. + + + + + Organizational tools for team management and access control. + + + + Associate email lists with user groups for team organization + + + Get all user groups for permissions and organizational management + + + + + + Track and analyze email engagement metrics and subscriber behavior. + + + + Monitor email opens, clicks, and other engagement activities + + + + + For best results, always use filters when calling this tool rather than requesting all activities at once. + + + + +--- + +## Resources + +The ActiveCampaign server provides direct access to platform data through resource endpoints that complement the tool-based operations. + + + + Access entire data collections for browsing and discovery: + + + + `activecampaign://contacts` + Access the complete contact database + + + `activecampaign://lists` + Browse all email lists and segments + + + `activecampaign://automations` + View all automation workflows + + + `activecampaign://campaigns` + Access campaign data and metrics + + + + + + Access specific records when you know their ID: + + + + `activecampaign://contacts/{id}` + Get detailed contact information + + + `activecampaign://lists/{id}` + Retrieve specific list configuration and stats + + + `activecampaign://automations/{id}` + Access automation workflow details + + + `activecampaign://campaigns/{id}` + Get campaign-specific performance data + + + + + **Pro Tip:** Use collection endpoints for discovery, then switch to individual record endpoints for detailed operations. + + + + diff --git a/nexus/reference/servers/coingecko.mdx b/nexus/reference/servers/coingecko.mdx new file mode 100644 index 00000000..77249786 --- /dev/null +++ b/nexus/reference/servers/coingecko.mdx @@ -0,0 +1,304 @@ +--- +title: "CoinGecko Server" +description: "Access comprehensive cryptocurrency data including prices, market caps, volumes, trending coins, DeFi protocols, and NFT markets" +icon: "server" +--- + +# CoinGecko Server + +## Overview + +The CoinGecko server provides the world's most comprehensive cryptocurrency data platform. Built by [CoinGecko](https://www.coingecko.com), this server enables AI assistants to access real-time prices, market data, DeFi protocols, NFT information, and on-chain analytics across 400+ exchanges and thousands of cryptocurrencies. + +## Getting Started + + + + Add the CoinGecko server to your Nexus environment through the server directory. + + + CoinGecko server uses public API endpoints that don't require authentication. + + + Start with `get_coins_markets` to see current market data or `get_search` to explore available coins. + + + +## What You Can Do + + + + Real-time prices, market caps, volumes, and price changes across thousands of cryptocurrencies + + + DEX trading data, liquidity pools, token analytics, and on-chain metrics + + + NFT collection prices, market charts, and trending digital assets + + + Historical price data, OHLCV charts, and time-series analysis + + + +## Use Cases + + + + - **Price Monitoring**: Track real-time prices and market movements + - **Market Analysis**: Analyze market caps, volumes, and price trends + - **Portfolio Tracking**: Monitor investments across different cryptocurrencies + - **Top Gainers/Losers**: Identify opportunities and market movers + - **Historical Analysis**: Study price patterns and historical performance + + + + - **DEX Analysis**: Track decentralized exchange trading volumes and liquidity + - **Token Research**: Analyze token metrics, holder data, and on-chain activity + - **Liquidity Pools**: Monitor pool performance and yield opportunities + - **Trending Pools**: Discover popular and emerging DeFi protocols + - **Cross-Chain Analysis**: Compare metrics across different blockchain networks + + + + - **Coin Discovery**: Find new and trending cryptocurrencies + - **Category Analysis**: Explore different crypto sectors (DeFi, NFT, Gaming, etc.) + - **Platform Research**: Understand different blockchain platforms and their ecosystems + - **Market Trends**: Identify trending coins and market sentiment + - **Competitive Analysis**: Compare similar projects and their performance + + + + - **Market Reports**: Generate comprehensive market analysis reports + - **Price Alerts**: Monitor price thresholds and market conditions + - **Research Documentation**: Gather data for investment or research purposes + - **API Integration**: Feed crypto data into applications and dashboards + - **Educational Content**: Create educational materials with current market data + + + +--- + +## Available Tools (44) + + + + Essential tools for cryptocurrency prices, market caps, and basic market information. + + **Price and Market Data** + + + **Primary market data tool** - Get prices, market caps, volumes, and market data + - **Parameters**: vs_currency (required), category, ids, symbols, order, pagination + - **Data**: Current price, market cap, volume, 24h changes, ATH/ATL, market cap rank + + + Quick price lookups for specific coins in multiple currencies + - **Use Cases**: Simple price checks, portfolio valuation, quick comparisons + + + Top 30 coins with largest price gains and losses by time duration + - **Timeframes**: 1h, 24h, 7d, 14d, 30d, 60d, 1y + + + Complete metadata and market data for specific coins by ID + - **Data**: Full coin details, market data, social links, developer data + + + Global cryptocurrency market overview and statistics + - **Data**: Total market cap, total volume, market dominance, DeFi stats + + + Historical data for a specific coin on a particular date + - **Use Cases**: Point-in-time analysis, historical comparisons + + + Search for coins, categories, markets, and trending searches + - **Scope**: Coins, exchanges, categories, NFTs + + + + + Always use `jq_filter` parameter to reduce response size and improve performance. + + + + + Tools for discovering cryptocurrencies and understanding the CoinGecko ecosystem. + + + + Complete list of all supported coins with IDs, names, and symbols + - **Parameters**: include_platform (contract addresses), status (active/inactive) + + + Latest 200 coins recently listed on CoinGecko + - **Use Cases**: Discovery of new projects, early-stage research + + + All coin categories available on CoinGecko + - **Categories**: DeFi, NFT, Gaming, Layer 1, Layer 2, etc. + + + Currently trending search terms and coins + - **Data**: Top searches, trending coins, trending NFTs + + + + + + Comprehensive historical price data and charting information. + + + + Historical price, market cap, and volume data within date ranges + - **Parameters**: coin ID, vs_currency, from/to timestamps + + + OHLC (Open, High, Low, Close) candle data for specific time ranges + - **Use Cases**: Technical analysis, candlestick charting + + + Historical data for tokens by contract address + - **Use Cases**: Token-specific analysis, contract-based tracking + + + Token data by blockchain platform and contract address + - **Platforms**: Ethereum, BSC, Polygon, Arbitrum, etc. + + + + + + Advanced DeFi protocol data, liquidity pools, and on-chain metrics. + + **Network and DEX Data** + + + All supported blockchain networks for on-chain data + + + Decentralized exchanges on specific networks + + + On-chain data categories and classifications + + + Liquidity pool categories across DeFi protocols + + + + **Pool Analysis Tools** + + + Trending liquidity pools on specific networks + + + Recently created liquidity pools + + + Comprehensive pool data including TVL, volume, APY + + + Detailed information about specific liquidity pools + + + Recent trades and transactions for specific pools + + + + **Token Analytics** + + + Comprehensive token information including supply, holders + + + Top token holders and distribution analysis + + + Liquidity pools containing specific tokens + + + Recent trading activity for specific tokens + + + + + DeFi tools require specific network and address parameters. Use discovery tools first to find valid IDs. + + + + + NFT collection data, market trends, and digital asset analytics. + + + + List of supported NFT collections with basic information + - **Parameters**: order (market_cap, volume, id), per_page, asset_platform_id + + + Detailed NFT collection data including floor price, market cap + - **Data**: Collection stats, social links, description, market metrics + + + Historical market chart data for NFT collections + - **Metrics**: Floor price, market cap, volume over time + + + + + NFT data includes floor prices, market caps, and trading volumes for major collections. + + + + +--- + +## Configuration Requirements + +### Server Configuration +- **Transport**: Server-Sent Events (SSE) - `sse` transport type +- **Endpoint**: `https://mcp.api.coingecko.com/sse` (remote server) +- **Authentication**: None required - uses public API endpoints +- **Rate Limits**: Standard rate limits apply based on CoinGecko's public API tiers + + +CoinGecko server uses remote SSE transport and doesn't require authentication for public data access. + + +## Best Practices + +### Performance Optimization +1. **Use jq_filter**: Always include `jq_filter` parameter to reduce response size and improve performance +2. **Pagination**: Use `page` and `per_page` parameters for large datasets +3. **Specific Queries**: Use coin IDs or symbols instead of fetching all coins when possible +4. **Cache Results**: Cache frequently accessed data to reduce API calls + +### Data Filtering and Search +1. **JQ Filters**: Learn basic jq syntax for efficient data extraction + - `.[] | {name, symbol, current_price}` - Extract specific fields + - `.[:10]` - Limit to first 10 results + - `.[] | select(.market_cap_rank <= 100)` - Filter by criteria +2. **Currency Selection**: Use appropriate `vs_currency` for your target audience +3. **Precision Settings**: Use `precision` parameter for price display accuracy + +### Market Analysis Workflows +1. **Market Overview**: Start with `get_coins_markets` for general market conditions +2. **Specific Analysis**: Use `get_id_coins` for detailed single-coin research +3. **Historical Context**: Add `get_range_coins_market_chart` for price history +4. **Trend Analysis**: Use `get_coins_top_gainers_losers` for market movers +5. **Discovery**: Use `get_search_trending` and `get_new_coins_list` for opportunities + +### DeFi Research Strategy +1. **Network Discovery**: Start with `get_onchain_networks` to understand available chains +2. **Pool Analysis**: Use `get_networks_onchain_trending_pools` for popular protocols +3. **Token Research**: Combine `get_tokens_networks_onchain_info` with holder analysis +4. **Cross-Reference**: Compare on-chain data with market data tools + + +CoinGecko API has rate limits. For high-frequency access or commercial use, consider CoinGecko's paid API plans. + + + +**Pro Tip**: Use `get_search` to find exact coin IDs before using other tools. Many tools require specific CoinGecko coin IDs rather than symbols. + diff --git a/nexus/reference/servers/dropbox.mdx b/nexus/reference/servers/dropbox.mdx new file mode 100644 index 00000000..a0a2b624 --- /dev/null +++ b/nexus/reference/servers/dropbox.mdx @@ -0,0 +1,193 @@ +--- +title: "Dropbox Server" +description: "Access and search files in your Dropbox with upload and search capabilities" +icon: "server" +--- + +# Dropbox Server + +## Overview + +The Dropbox server provides essential file management capabilities for your Dropbox account. Built by [Dropbox](https://dropbox.com), this server enables AI assistants to search files, upload content, and access your cloud storage directly. + +## Getting Started + + + + Add the Dropbox server to your Nexus environment through the server directory. + + + Connect your Dropbox account using OAuth to access your files and folders. + + + Start with a simple `search` command to verify access and explore your files. + + + +## What You Can Do + + + + Search for files across your entire Dropbox or within specific folders + + + Upload new files directly to your Dropbox with base64 encoded content + + + Search within specific folder paths for targeted file discovery + + + Organize and access your cloud storage through AI assistant interactions + + + +## Use Cases + + + + - **File Discovery**: Find documents, spreadsheets, and presentations across your Dropbox + - **Content Search**: Search file names and metadata to locate specific resources + - **Organization**: Navigate folder structures and understand file organization + - **Quick Access**: Retrieve files without manually browsing through folders + + + + - **Document Upload**: Create and upload new files directly from AI conversations + - **Content Backup**: Store generated content, reports, and data files + - **Collaborative Storage**: Upload files for team access and sharing + - **Automated Archiving**: Store conversation outputs and generated materials + + + + - **Data File Access**: Find and analyze CSV files, databases, and datasets + - **Report Storage**: Access existing reports and analysis documents + - **Reference Material**: Locate research papers, documentation, and resources + - **Version Control**: Find different versions of documents and compare changes + + + + - **Asset Discovery**: Find project files, images, and resources + - **Documentation Access**: Locate project documentation and specifications + - **File Sharing Preparation**: Search for files that need to be shared or distributed + - **Archive Management**: Access historical project files and documentation + + + +--- + +## Available Tools (3) + + + + Comprehensive search capabilities for finding files across your Dropbox storage. + + **Global and Targeted Search** + + + Search for files across your entire Dropbox account + - **Parameters**: query (required) - search term for file names and metadata + - **Scope**: Searches all accessible files and folders + - **Use Cases**: Find files by name, type, or content when location is unknown + + + Search for files within a specific Dropbox folder + - **Parameters**: query (required), path (optional), max_results (optional) + - **Scope**: Limited to specified folder path for targeted results + - **Performance**: Faster searches when you know the general location + + + + + **Search Tips**: Use specific keywords, file extensions (.pdf, .docx), or partial file names for better results. + + + + + Upload and store new files directly in your Dropbox storage. + + + + Upload new files to your Dropbox with base64 encoded content + - **Parameters**: + - path (required): Target location in Dropbox (e.g., "/documents/report.pdf") + - content (required): Base64 encoded file content + - **Supported Formats**: Any file type that can be base64 encoded + - **Use Cases**: Save generated documents, upload analysis results, store conversation outputs + + + + + File content must be base64 encoded. Large files may have upload limits based on your Dropbox account tier. + + + + +--- + +## Configuration Requirements + +### Authentication Setup +The Dropbox server uses OAuth2 authentication with specific file access scopes: + + + + **Required Permissions:** + - **files.metadata.read**: Read file and folder metadata (for search operations) + - **files.content.read**: Read file content (for comprehensive access) + - **files.content.write**: Write and upload files (for upload operations) + + **Tool-Specific Scopes:** + - `search` and `search_file_db`: files.metadata.read + - `upload_file`: files.content.read + files.content.write + + + + - **Dropbox Account**: Personal or business Dropbox account + - **Storage Space**: Sufficient storage for upload operations + - **API Access**: Dropbox API access enabled (typically available for all accounts) + + + +### Server Configuration +- **Transport**: STDIO-hosted (requires Hub Bridge) +- **Hub Bridge**: Uses `npx -y @civic/hub-bridge` for OAuth authentication +- **File Encoding**: Base64 encoding required for file uploads +- **Path Format**: Unix-style paths (e.g., "/folder/subfolder/file.ext") + + +The Dropbox server requires Hub Bridge for secure OAuth token management and API interactions. + + +## Best Practices + +### File Search Strategies +1. **Start Broad**: Use general terms first, then narrow down with specific keywords +2. **Use Extensions**: Include file extensions (.pdf, .xlsx, .png) to filter by type +3. **Folder-Specific**: Use `search_file_db` when you know the approximate location +4. **Pagination**: Use max_results parameter to control search result volume + +### File Upload Guidelines +1. **Path Planning**: Use clear, descriptive folder structures (e.g., "/projects/2024/reports/") +2. **File Naming**: Use descriptive names with dates or version numbers +3. **Encoding Verification**: Ensure proper base64 encoding before upload +4. **Size Considerations**: Be aware of file size limits and account storage capacity + +### Organization & Management +1. **Consistent Naming**: Use consistent file naming conventions for better searchability +2. **Folder Structure**: Maintain organized folder hierarchies for efficient searching +3. **Regular Cleanup**: Periodically search for and organize files to maintain structure +4. **Backup Strategy**: Use uploads to create backups of important generated content + +### Integration Workflows +1. **Document Generation**: Generate content and immediately upload to Dropbox for storage +2. **Research Workflows**: Search for existing files before creating new documents +3. **Collaboration**: Upload files to shared folders for team access +4. **Archive Management**: Use search to maintain and organize historical files + + +Always verify file paths and ensure you have appropriate permissions before uploading files. Incorrect paths may create unintended folder structures. + + + +**Pro Tip**: Combine search operations with upload operations - search for existing files first to avoid duplicates, then upload new versions with updated names. + diff --git a/nexus/reference/servers/github.mdx b/nexus/reference/servers/github.mdx new file mode 100644 index 00000000..ec3ea950 --- /dev/null +++ b/nexus/reference/servers/github.mdx @@ -0,0 +1,311 @@ +--- +title: "GitHub Server" +description: "Connect to GitHub repositories for development workflows, issue management, and code operations" +icon: "server" +--- + +# GitHub Server + +## Overview + +The GitHub server provides comprehensive integration with [GitHub](https://github.com) repositories, enabling AI assistants to manage issues, pull requests, code files, and development workflows programmatically. + +## Getting Started + + + + Add the GitHub server to your Nexus environment through the server directory. + + + Start with a simple tool like `get_me` or `search_repositories` to verify the connection works properly. + + + +## What You Can Do + + + + Create, update, and track issues across repositories with full comment management + + + Manage PRs from creation to merge, including reviews, comments, and status checks + + + Read, create, and modify files directly in repositories with branch management + + + Search across repositories, code, users, and issues to find relevant information + + + +## Use Cases + + + + - **PR Creation**: Automatically create pull requests from feature branches with proper descriptions + - **Code Reviews**: Generate review comments and suggestions based on code changes + - **Issue Triage**: Automatically label and assign issues based on content analysis + - **Branch Management**: Create feature branches and manage merge workflows + + + + - **Issue Tracking**: Monitor project progress through issue creation and updates + - **Status Reports**: Generate project status reports from commit history and PR activity + - **Team Coordination**: Track team member contributions and code review assignments + - **Release Management**: Coordinate releases by analyzing commit history and issue resolution + + + + - **Code Search**: Find similar patterns, functions, or implementations across repositories + - **Documentation Updates**: Automatically update documentation based on code changes + - **Security Monitoring**: Track and respond to security scanning alerts + - **Dependency Analysis**: Monitor repository dependencies and update requirements + + + +--- + +## Available Tools + +Tool counts may change as the server evolves. See individual categories below for current capabilities. + + + + Authentication and user information management. + + + + Get details of the authenticated user including profile information and permissions + + + + + + Complete issue lifecycle management including creation, updates, and comments. + + **Core Issue Operations** + + + Get the complete contents and metadata of a specific issue within a repository + + + Create new issues with title, description, labels, and assignees + + + List all issues in a repository with filtering and sorting options + + + Update existing issues including status, labels, assignees, and descriptions + + + Search for issues across repositories using GitHub's powerful search syntax + + + + **Issue Comments** + + + Retrieve all comments for a specific issue including author and timestamp information + + + Add new comments to existing issues for collaboration and updates + + + + + + Comprehensive pull request workflows from creation to merge. + + **PR Core Operations** + + + Get complete details of a pull request including metadata, status, and changes + + + Create new pull requests with title, description, and branch specifications + + + List all pull requests in a repository with filtering by status, author, or branch + + + Update PR title, description, labels, or other metadata + + + Merge approved pull requests using different merge strategies + + + + **PR Analysis** + + + Get list of files changed in a pull request with diff information + + + Check the status of pull request including CI/CD checks and review status + + + Update pull request branch with latest changes from base branch + + + + **PR Collaboration** + + + Retrieve all comments on a pull request for review and discussion + + + Get all code reviews and their status (approved, changes requested, etc.) + + + Create comprehensive code reviews with comments and approval status + + + Add specific line-by-line comments during code review process + + + Request automated code review assistance from GitHub Copilot + + + + + + Direct file manipulation and code management within repositories. + + + + Create new files or update existing files in repositories with commit messages + + + Read the contents of any file in a repository with support for different branches + + + Push multiple file changes to a repository in a single commit + + + + + + Repository-level operations including creation, forking, and discovery. + + + + Search for repositories across GitHub using various criteria and filters + + + Create new repositories with specified settings, visibility, and initial content + + + Fork existing repositories to your account or organization for contributions + + + + + + Git workflow management including branching, commits, and history. + + + + List all branches in a repository with their latest commit information + + + Create new branches from existing branches for feature development + + + Get commit history for a repository or specific branch with author and message details + + + Get detailed information about a specific commit including file changes + + + + + + Advanced search capabilities across GitHub's entire platform. + + + + Search for specific code patterns, functions, or implementations across repositories + + + Find GitHub users based on various criteria like location, followers, or repositories + + + + + + Security monitoring and vulnerability management tools. + + + + Get details of specific code security alerts and vulnerabilities + + + List all code scanning security alerts for a repository + + + Get details of secret scanning alerts for exposed credentials + + + List all secret scanning alerts to identify exposed sensitive information + + + + + +--- + +## Resources + +The GitHub server provides direct access to GitHub data through resource endpoints. + + + + Access entire data collections for browsing and discovery: + + + + `github://repositories` + Access repository listings and metadata + + + `github://issues` + Browse issues across accessible repositories + + + `github://pull-requests` + View pull request data and status + + + `github://users` + Access user profiles and information + + + + + + Access specific records when you know their ID: + + + + `github://repositories/{owner}/{repo}` + Get specific repository details + + + `github://issues/{owner}/{repo}/{number}` + Get individual issue details + + + `github://pull-requests/{owner}/{repo}/{number}` + Get specific pull request information + + + `github://users/{username}` + Get user profile and activity + + + + + **Pro Tip:** Use collection endpoints to discover repositories and issues, then switch to individual record endpoints for detailed operations. + + + diff --git a/nexus/reference/servers/hubspot.mdx b/nexus/reference/servers/hubspot.mdx new file mode 100644 index 00000000..41a7fdfe --- /dev/null +++ b/nexus/reference/servers/hubspot.mdx @@ -0,0 +1,310 @@ +--- +title: "HubSpot Server" +description: "Access and manage HubSpot CRM data, contacts, companies, deals, and comprehensive sales & marketing workflows" +icon: "server" +--- + +# HubSpot Server + +## Overview + +The HubSpot server provides comprehensive CRM and marketing automation capabilities. Built by [HubSpot](https://hubspot.com), this server enables AI assistants to manage contacts, companies, deals, workflows, and complete sales & marketing operations. + +## Getting Started + + + + Add the HubSpot server to your Nexus environment through the server directory. + + + Connect your HubSpot account using OAuth to access your CRM data and marketing tools. + + + Start with `hubspot-get-user-details` to verify authentication and `hubspot-list-objects` to explore your data. + + + +## What You Can Do + + + + Manage contacts, companies, deals, and tickets with full CRUD operations + + + Create engagements, manage workflows, and track marketing campaigns + + + Configure custom properties, schemas, and object relationships + + + Track deals, manage sales processes, and optimize conversion workflows + + + +## Use Cases + + + + - **Contact Management**: Create, update, and organize customer contacts with rich profile data + - **Company Profiles**: Maintain comprehensive company records with industry, size, and relationship data + - **Deal Tracking**: Monitor sales opportunities from lead to close with stage management + - **Ticket Management**: Handle customer support requests and track resolution progress + + + + - **Campaign Management**: Organize contacts into campaigns and track engagement metrics + - **Workflow Automation**: Create automated sequences for lead nurturing and customer onboarding + - **Engagement Tracking**: Log calls, emails, meetings, and tasks for complete customer history + - **Lead Scoring**: Develop and maintain lead scoring models based on behavior and demographics + + + + - **Pipeline Management**: Configure sales stages and track deal progression + - **Activity Logging**: Record sales activities and maintain comprehensive interaction history + - **Performance Analytics**: Analyze sales metrics, conversion rates, and team performance + - **Territory Management**: Organize accounts by geography, industry, or sales rep + + + + - **Custom Properties**: Create custom fields for specific business requirements + - **Object Associations**: Link contacts, companies, deals, and custom objects + - **Data Import/Export**: Bulk manage data with batch operations for efficiency + - **Schema Management**: Configure custom object types and their relationships + + + +--- + +## Available Tools (21) + + + + Essential tools for authentication and exploring your HubSpot environment. + + **Account Management** + + + Authenticate and analyze access token permissions and account details + - **Use Cases**: Verify authentication, understand account permissions + + + Retrieve all custom object schemas in your HubSpot account + - **Use Cases**: Understand available object types and their structure + + + + + Start with `hubspot-get-user-details` to verify your authentication and understand available permissions. + + + + + Core CRM functionality for managing contacts, companies, deals, and custom objects. + + **CRUD Operations** + + + Retrieve paginated lists of any HubSpot object type + - **Parameters**: objectType (required), pagination, filters, properties, associations + - **Object Types**: contacts, companies, deals, tickets, custom objects + + + Perform advanced filtered searches with complex criteria + - **Features**: Filter groups, sorting, query strings, property selection + - **Use Cases**: Find specific records, complex business logic queries + + + Create multiple objects of the same type in one operation + - **Efficiency**: Bulk operations for data imports and migrations + - **Associations**: Create relationships during object creation + + + Update multiple existing objects efficiently in batch operations + - **Use Cases**: Bulk data updates, synchronized field changes + + + Retrieve multiple objects by their IDs in a single batch operation + - **Performance**: Efficient bulk data retrieval for reporting + + + + + **Common Object Types**: contacts, companies, deals, tickets, products, line_items, quotes, calls, emails, meetings, notes, tasks. + + + + + Tools for managing relationships between different HubSpot objects. + + + + Establish relationships between HubSpot objects across different types + - **Examples**: Link contact to company, associate deal with contact + - **Parameters**: fromObjectId, toObjectId, association types + + + Retrieve valid association types between specific object types + - **Use Cases**: Understand available relationship types before creating associations + + + Retrieve existing relationships for a specific object + - **Use Cases**: Find all companies associated with a contact, deals linked to accounts + + + + + Always use `hubspot-get-association-definitions` to verify valid association types before creating relationships. + + + + + Configure and manage custom properties and data structure. + + + + Get complete catalog of properties for any HubSpot object type + - **Use Cases**: Understand available fields, data structure planning + + + Retrieve detailed information about a specific property + - **Details**: Property type, options, validation rules, usage + + + Create new custom properties for HubSpot object types + - **Customization**: Custom fields, dropdowns, calculations, formulas + + + Update existing custom properties and their configurations + - **Modifications**: Labels, options, validation, descriptions + + + + + **Property Types**: Single-line text, multi-line text, dropdown select, number, date, file, URL, and more. + + + + + Create and manage customer interactions, notes, and tasks. + + + + Create engagements (Notes or Tasks) associated with CRM objects + - **Types**: Notes, Tasks, Calls, Emails, Meetings + - **Associations**: Link to contacts, companies, deals, tickets + + + Retrieve engagement details by ID + - **Use Cases**: Review interaction history, task details + + + Update existing engagements with new information + - **Modifications**: Status, notes, due dates, priorities + + + + + **Engagement Types**: Note (for logging interactions), Task (for follow-up activities). + + + + + Manage marketing automation workflows and business processes. + + + + Retrieve paginated list of workflows in your HubSpot account + - **Use Cases**: Discover automation, understand workflow structure + + + Get detailed information about a specific workflow + - **Details**: Actions, triggers, enrollment criteria, performance metrics + + + + + Workflows are read-only through the API - creation and editing must be done through the HubSpot interface. + + + + + Helpful utilities for navigation and support. + + + + Generate HubSpot UI links for different pages and objects + - **Link Types**: Object records, list views, reports, settings + - **Use Cases**: Direct navigation to HubSpot interface, sharing specific records + + + + + +--- + +## Configuration Requirements + +### Authentication Setup +The HubSpot server uses OAuth2 authentication with HubSpot's API: + + + + **Required Scopes for Full Functionality:** + - **CRM Objects**: Read/write access to contacts, companies, deals, tickets + - **Properties**: Manage custom properties and object schemas + - **Associations**: Create and manage object relationships + - **Engagements**: Create and manage notes, tasks, and activities + - **Workflows**: Read access to automation workflows + + + + - **HubSpot Account**: Free or paid HubSpot account with CRM access + - **API Access**: Ensure API access is enabled for your account tier + - **Permissions**: Admin or appropriate role permissions for the operations you need + - **Rate Limits**: Be aware of HubSpot's API rate limits based on your account tier + + + +### Server Configuration +- **Transport**: STDIO-hosted (local Hub Bridge required) +- **Hub Bridge**: Uses `npx -y @civic/hub-bridge` for authentication and requests +- **API Integration**: Direct connection to HubSpot's REST API +- **Rate Limiting**: Automatic rate limit handling with retry logic + + +The HubSpot server requires Hub Bridge for authentication management and API request handling. + + +## Best Practices + +### CRM Data Management +1. **Object Strategy**: Use `hubspot-list-objects` to understand your current data structure +2. **Search Optimization**: Use `hubspot-search-objects` for complex queries instead of filtering large lists +3. **Batch Operations**: Use batch tools for bulk operations to improve performance and avoid rate limits +4. **Property Planning**: Use `hubspot-list-properties` before creating custom fields + +### Association Management +1. **Relationship Discovery**: Use `hubspot-get-association-definitions` to understand available relationships +2. **Systematic Linking**: Create associations systematically (contact → company → deal) +3. **Association Cleanup**: Regularly audit and clean up unnecessary associations +4. **Performance Impact**: Consider association queries impact on API performance + +### Workflow Integration +1. **Automation Audit**: Use `hubspot-list-workflows` to understand existing automations +2. **Engagement Logging**: Create engagements to maintain comprehensive customer interaction history +3. **Data Consistency**: Ensure data quality with property validation and required fields +4. **Performance Monitoring**: Monitor API usage to stay within rate limits + +### Sales Process Optimization +1. **Deal Pipeline**: Structure deals with consistent stages and properties +2. **Activity Tracking**: Log all customer interactions as engagements +3. **Custom Properties**: Create custom fields for business-specific requirements +4. **Reporting Data**: Structure data to support reporting and analytics needs + + +HubSpot has strict rate limits that vary by account tier. Use batch operations when possible and implement proper error handling for rate limit responses. + + + +**Pro Tip**: Start with read operations to understand your data structure before implementing create/update operations. Use the HubSpot UI to verify API changes during development. + diff --git a/nexus/reference/servers/linear.mdx b/nexus/reference/servers/linear.mdx new file mode 100644 index 00000000..92696224 --- /dev/null +++ b/nexus/reference/servers/linear.mdx @@ -0,0 +1,249 @@ +--- +title: "Linear Server" +description: "Streamline your workflow with Linear's issue tracking and project management tools" +icon: "server" +--- + +# Linear Server + +## Overview + +The Linear server provides comprehensive project management and issue tracking capabilities. Built by [Linear](https://linear.app), this server enables AI assistants to manage issues, coordinate projects, track sprints, and streamline development workflows. + +## Getting Started + + + + Add the Linear server to your Nexus environment through the server directory. + + + Connect your Linear workspace using OAuth to access your teams and projects. + + + Start with `get user` to verify authentication and `list teams` to see your workspace structure. + + + +## What You Can Do + + + + Create, update, search, and track issues across teams and projects + + + Manage projects, assign leads, set timelines, and track progress + + + Coordinate teams, workflows, and sprint cycles for efficient delivery + + + Automate issue creation, updates, and status transitions based on development events + + + +## Use Cases + + + + - **Bug Reporting**: Create detailed bug reports with descriptions, priorities, and assignments + - **Feature Requests**: Track feature development from concept to completion + - **Task Management**: Organize development tasks with estimates and deadlines + - **Status Tracking**: Monitor issue progress through customizable workflow states + + + + - **Project Setup**: Create projects with timelines, leads, and team assignments + - **Sprint Planning**: Organize work into cycles with clear start and end dates + - **Progress Monitoring**: Track project completion and identify blockers + - **Resource Allocation**: Balance workload across team members and projects + + + + - **Cross-team Coordination**: Manage dependencies between different teams + - **Communication**: Add comments and updates to issues for clear communication + - **Assignment Management**: Distribute work based on expertise and availability + - **Workflow Standardization**: Ensure consistent processes across teams + + + + - **Code-to-Issue Linking**: Connect code changes to specific Linear issues + - **Automated Updates**: Update issue status based on Git commits and deployments + - **Release Planning**: Organize issues into releases and track completion + - **Quality Assurance**: Track testing, reviews, and deployment status + + + +--- + +## Available Tools (14) + + + + Essential tools for understanding workspace structure and team organization. + + **Workspace Discovery** + + + Get information about the authenticated Linear user and workspace access + + + List all teams in the workspace with optional archived team inclusion + - **Parameters**: includeArchived (boolean, default: false) + + + List all users in the workspace with activity status + - **Parameters**: includeInactive (boolean, default: false) + + + + + **Team IDs**: Required for most operations - get them via `list_teams` first. + + + + + Core functionality for creating, updating, and managing Linear issues. + + **Issue Lifecycle Management** + + + Advanced issue search with multiple filter options + - **Filters**: query, teamId, projectId, assigneeId, state, limit (1-100) + - **States**: backlog, todo, in_progress, done, canceled + + + Get detailed information about specific issues + - **Input**: Issue ID or issue number (e.g., 'ENG-123') + + + Create new issues with full metadata support + - **Required**: title, teamId + - **Optional**: description, projectId, assigneeId, priority (0-4), labelIds, estimate + + + Update existing issues with flexible field modifications + - **Updatable**: title, description, stateId, assigneeId, priority, labelIds, estimate + + + Add markdown-formatted comments to issues for collaboration + - **Parameters**: issueId (required), body (markdown format) + + + + + **Priority Levels**: 0=No priority, 1=Urgent, 2=High, 3=Normal, 4=Low + + + + + Tools for organizing work into projects and tracking progress. + + + + List projects with team and archive filtering + - **Parameters**: teamId (optional), includeArchived (boolean, default: false) + + + Create new projects with timeline and team assignments + - **Required**: name, teamIds (array) + - **Optional**: description, leadId, targetDate, startDate (YYYY-MM-DD) + + + List sprint cycles for agile development + - **Parameters**: teamId (required), includeCompleted (boolean, default: false) + + + + + **Date Format**: Use ISO date format (YYYY-MM-DD) for startDate and targetDate parameters. + + + + + Tools for managing workflow states, labels, and team configuration. + + + + Get workflow states and transitions for specific teams + - **Parameters**: teamId (required) + - **Use Cases**: Understand available states for issue updates + + + List available labels for categorizing and organizing issues + - **Parameters**: teamId (optional filter) + - **Use Cases**: Get label IDs for issue creation and updates + + + + + Always use `list_workflows` to get valid stateIds before updating issue states. + + + + +--- + +## Configuration Requirements + +### Authentication Setup +The Linear server uses OAuth2 authentication with Linear's API: + + + + - **Read Access**: View issues, projects, teams, and user data + - **Write Access**: Create and update issues, projects, and comments + - **Workspace Access**: Access to all teams and projects in your workspace + + + + - **Team Member**: Must be a member of teams you want to manage + - **Project Access**: View and edit permissions for relevant projects + - **Issue Management**: Create, update, and comment permissions + - **User Directory**: Access to workspace user list for assignments + + + +### Server Configuration +- **Transport**: HTTP-based remote server +- **Endpoint**: `https://mcp.linear.app/mcp` +- **API Integration**: Direct connection to Linear's GraphQL API +- **Real-time Updates**: Supports live data synchronization + + +The Linear server connects directly to Linear's API infrastructure for optimal performance and real-time data access. + + +## Best Practices + +### Issue Management Workflow +1. **Team Discovery**: Use `list_teams` to understand workspace structure +2. **Issue Creation**: Use `create_issue` with appropriate team, priority, and labels +3. **Progress Tracking**: Use `search_issues` with state filters to monitor progress +4. **Status Updates**: Use `update_issue` to move issues through workflow states +5. **Communication**: Use `add_comment` for updates and collaboration + +### Project Planning Best Practices +1. **Project Setup**: Use `create_project` with clear timelines and team assignments +2. **Sprint Organization**: Use `list_cycles` to plan work in iterations +3. **Workload Distribution**: Balance assignments using `list_users` and search filters +4. **Progress Monitoring**: Track project completion with filtered issue searches + +### Workflow Optimization +1. **State Management**: Use `list_workflows` to understand available transitions +2. **Label Strategy**: Use `list_labels` to maintain consistent categorization +3. **Automation**: Create issues automatically based on errors, deployments, or events +4. **Integration**: Link issues to code commits, pull requests, and deployments + +### Team Coordination +1. **Assignment Strategy**: Assign issues based on expertise and current workload +2. **Priority Management**: Use priority levels consistently across teams +3. **Communication**: Keep issue comments updated with progress and blockers +4. **Cross-team Dependencies**: Use projects to coordinate work between teams + + +Always verify team IDs, user IDs, and state IDs using the list tools before creating or updating issues. + + + +**Pro Tip**: Use descriptive issue titles and markdown-formatted descriptions for better searchability and team communication. + diff --git a/nexus/reference/servers/n8n.mdx b/nexus/reference/servers/n8n.mdx new file mode 100644 index 00000000..ce82b31d --- /dev/null +++ b/nexus/reference/servers/n8n.mdx @@ -0,0 +1,209 @@ +--- +title: "n8n Server" +description: "Connect to n8n instances for workflow automation, execution management, and integration workflows" +icon: "server" +--- + +# n8n Server + +## Overview + +The n8n server provides comprehensive integration with [n8n](https://n8n.io) automation platform, enabling AI assistants to manage workflows, monitor executions, and trigger automations programmatically. + +## Getting Started + + + + Add the n8n server to your Nexus environment through the server directory. + + + Provide your n8n instance API URL and API key for authentication. + + + Start with a simple command like `list workflows` to verify the connection works properly. + + + +## What You Can Do + + + + Create, update, activate, and delete n8n workflows programmatically + + + Track workflow executions, view results, and monitor automation performance + + + Execute workflows via webhook calls with custom input data and headers + + + Activate and deactivate workflows to control when automations run + + + +## Use Cases + + + + - **Dynamic Workflow Creation**: Build workflows programmatically based on business requirements + - **Conditional Automation**: Activate/deactivate workflows based on schedules or events + - **Bulk Operations**: Manage multiple workflows simultaneously across projects + - **Integration Orchestration**: Coordinate complex multi-step automations + + + + - **Execution Tracking**: Monitor workflow success rates and performance metrics + - **Error Analysis**: Identify and analyze failed executions for troubleshooting + - **Performance Optimization**: Track execution duration and optimize slow workflows + - **Audit Trail**: Maintain logs of workflow changes and execution history + + + + - **Webhook Integration**: Trigger workflows from external systems via webhooks + - **Data Processing**: Process incoming data through automated workflow pipelines + - **Notification Systems**: Set up automated alerts and notification workflows + - **API Orchestration**: Chain multiple API calls through workflow automation + + + +--- + +## Available Tools (11) + + + + Complete lifecycle management of n8n workflows from creation to deletion. + + **Core Workflow Operations** + + + Retrieve a list of all workflows with optional filtering by active/inactive status + + + Retrieve detailed information about a specific workflow by ID + + + Create new workflows with nodes, connections, and configuration settings + + + Modify existing workflows including nodes, connections, and metadata + + + Remove workflows permanently from the n8n instance + + + + **Workflow State Management** + + + Enable workflows to run automatically based on their trigger conditions + + + Disable workflows to prevent automatic execution while preserving configuration + + + + + + Monitor and manage workflow execution history and results. + + + + Retrieve workflow executions with filtering by workflow, status, and pagination support + + + Get detailed execution information including node results and error data + + + Remove specific execution records from the execution history + + + + + Use status filters ('success', 'error', 'waiting', 'canceled') to find specific execution types quickly. + + + + + Execute workflows via HTTP webhooks with custom data and headers. + + + + Trigger workflow execution via webhook with optional input data and custom headers + + + + + **Pro Tip:** Use meaningful workflow names for webhook endpoints and include error handling in your workflows for robust webhook processing. + + + + +--- + +## Resources + +The n8n server provides direct access to workflow and execution data through resource endpoints. + + + + Access entire data collections for browsing and discovery: + + + + `n8n://workflows` + Access the complete workflow directory + + + `n8n://execution-stats` + View execution metrics and performance data + + + + + + Access specific records when you know their ID: + + + + `n8n://workflows/{id}` + Get comprehensive workflow information including nodes and connections + + + `n8n://executions/{id}` + Get detailed execution results including node outputs and error information + + + + + **Pro Tip:** Use collection endpoints to discover workflows and executions, then switch to individual record endpoints for detailed analysis. + + + + +## Configuration Requirements + +### Authentication Setup +The n8n server requires API key authentication with your n8n instance: + + + + - **API Key**: Your n8n instance API key (generated in n8n Settings → API Keys) + - **API URL**: Your n8n instance API endpoint (e.g., `https://n8n.example.com/api/v1`) + - **Webhook Credentials** (optional): Username/password for webhook authentication + + + + - **Default API URL**: `https://n8n.civic.com/api/v1` + - **Default Webhook Username**: `username` + - **Default Webhook Password**: `password` + + + + +Ensure your n8n instance is accessible from the internet and API access is enabled in your n8n configuration. + + + +The n8n server requires appropriate API permissions in your n8n instance to create, modify, and execute workflows. + diff --git a/nexus/reference/servers/notion.mdx b/nexus/reference/servers/notion.mdx new file mode 100644 index 00000000..d07879a1 --- /dev/null +++ b/nexus/reference/servers/notion.mdx @@ -0,0 +1,161 @@ +--- +title: Notion +description: Interact with Notion databases and pages to create, read, update, and delete content +icon: "server" +--- + +## Overview + +The Notion server provides comprehensive integration with [Notion](https://notion.so) workspaces, enabling AI assistants to manage databases, pages, blocks, and comments for enhanced productivity and knowledge management. + +## Getting Started + + + + Add the Notion server to your Nexus environment through the server directory. + + + Start with a simple command like `search for pages` or `list users` to verify the connection works properly. + + + +## What You Can Do + + + + Create, update, retrieve, and manage Notion pages with full content control + + + Query databases, create new databases, and manage database properties + + + Add blocks, append content, and structure information with rich text formatting + + + Manage comments, retrieve user information, and facilitate workspace collaboration + + + +## Available Tools + +### User Management + + + + `API-get-user` — Retrieve a specific user by user ID + + + + `API-get-users` — List all users in the workspace with pagination support + + + + `API-get-self` — Retrieve your token's bot user information + + + +### Database Operations + + + + `API-post-database-query` — Query a database with filters, sorts, and pagination + + + + `API-create-a-database` — Create a new database with specified properties + + + + `API-update-a-database` — Update database title, description, and properties + + + + `API-retrieve-a-database` — Retrieve database information and schema + + + +### Page Management + + + + `API-post-page` — Create a new page with properties, content, and cover + + + + `API-patch-page` — Update page properties, icon, cover, and archive status + + + + `API-retrieve-a-page` — Retrieve page content and properties + + + + `API-retrieve-a-page-property` — Retrieve a specific page property item + + + +### Block Management + + + + `API-get-block-children` — Retrieve all child blocks from a parent block + + + + `API-patch-block-children` — Append new blocks as children to existing blocks + + + + `API-retrieve-a-block` — Retrieve a specific block by block ID + + + + `API-update-a-block` — Update block content and properties + + + + `API-delete-a-block` — Delete a block from the page + + + +### Search & Comments + + + + `API-post-search` — Search pages and databases by title with filters and sorting + + + + `API-retrieve-a-comment` — Retrieve comments on a specific block or page + + + + `API-create-a-comment` — Create a new comment on a page + + + +## Use Cases + +### Knowledge Management +- **Content Creation**: "Create a new project page with task database and initial content" +- **Information Retrieval**: "Search for all pages related to 'quarterly planning'" +- **Documentation**: "Update the API documentation page with new endpoints" + +### Database Operations +- **Data Analysis**: "Query the customer database for all high-priority leads" +- **Project Tracking**: "Create a new project database with status and assignee properties" +- **Reporting**: "Retrieve all completed tasks from the sprint database" + +### Team Collaboration +- **Feedback Collection**: "Add a comment to the design review page" +- **User Management**: "List all workspace members and their roles" +- **Content Review**: "Get all comments on the proposal document" + +### Content Structure +- **Page Organization**: "Add bullet points and paragraphs to the meeting notes page" +- **Database Setup**: "Create a CRM database with contact properties and relationships" +- **Information Architecture**: "Retrieve all child pages from the company handbook" + + +The Notion server requires appropriate workspace permissions and OAuth2 authentication to access and modify content in your Notion workspace. + diff --git a/nexus/reference/servers/postgresql.mdx b/nexus/reference/servers/postgresql.mdx new file mode 100644 index 00000000..fa19f06a --- /dev/null +++ b/nexus/reference/servers/postgresql.mdx @@ -0,0 +1,200 @@ +--- +title: "PostgreSQL Server" +description: "Connect to PostgreSQL databases with advanced security, query optimization, and database health monitoring" +icon: "server" +--- + +# PostgreSQL Server + +## Overview + +The PostgreSQL server provides comprehensive database integration with advanced security features, query optimization tools, and database health monitoring. Built by [Crystal DBA](https://github.com/crystaldba/postgres-mcp), it supports both restricted (read-only with SQL validation) and unrestricted modes. + +## Getting Started + + + + Add the PostgreSQL server to your Nexus environment through the server directory. + + + Provide your PostgreSQL connection string with proper authentication and SSL settings. + + + Start with a simple command like `list schemas` to verify database connectivity. + + + +## What You Can Do + + + + Browse database schemas, tables, views, sequences, and extensions + + + Analyze execution plans, recommend indexes, and optimize query performance + + + Monitor database health, connections, buffer cache, and system metrics + + + Identify slow queries, resource usage patterns, and bottlenecks + + + +## Use Cases + + + + - **Schema Management**: Explore database structure and relationships + - **Object Discovery**: Find tables, views, sequences, and extensions across schemas + - **Health Monitoring**: Track database health metrics and system performance + - **Connection Analysis**: Monitor active connections and resource usage + + + + - **Execution Plan Analysis**: Understand query performance with EXPLAIN + - **Index Recommendations**: Get AI-powered index suggestions for better performance + - **Workload Analysis**: Analyze frequently executed queries for optimization opportunities + - **Hypothetical Indexes**: Test index scenarios without creating actual indexes + + + + - **Slow Query Detection**: Identify resource-intensive and slow-running queries + - **Resource Usage Tracking**: Monitor CPU, memory, and I/O usage patterns + - **Buffer Cache Analysis**: Optimize memory usage and cache hit ratios + - **Vacuum and Maintenance**: Monitor table maintenance and space usage + + + +--- + +## Available Tools (9) + + + + Explore and understand your PostgreSQL database structure. + + **Schema and Object Management** + + + List all schemas in the database for structural overview + + + List objects (tables, views, sequences, extensions) within a specific schema + + + Get detailed information about specific database objects including structure and metadata + + + + + **Object Types Supported**: tables, views, sequences, extensions - specify the type for targeted exploration. + + + + + Advanced query performance analysis and optimization tools. + + + + Analyze SQL execution plans with cost estimates and optional real-time statistics + - **Parameters**: SQL query, analyze mode (true/false), hypothetical indexes + - **Features**: Shows execution plans, cost estimates, and actual performance data + + + Analyze frequently executed queries and recommend optimal indexes + - **Methods**: DTA (Database Tuning Advisor) or LLM-based analysis + - **Limits**: Configurable maximum index size constraints + + + Analyze specific queries (up to 10) and get targeted index recommendations + - **Input**: List of SQL queries for analysis + - **Output**: Optimized index suggestions with performance impact estimates + + + + + When using `analyze` mode in `explain_query`, the query will actually execute. Use carefully with data-modifying queries. + + + + + Monitor database performance and identify optimization opportunities. + + + + Comprehensive database health analysis across multiple dimensions + - **Health Types**: all, buffer, connection, constraint, index, replication, sequence, vacuum + - **Features**: Connection monitoring, index health, buffer cache analysis, constraint validation + + + Identify resource-intensive queries using pg_stat_statements data + - **Sort Options**: total_time, mean_time, resources + - **Customizable Limits**: Configure number of queries to return + + + + + The `get_top_queries` tool requires the `pg_stat_statements` extension to be enabled in your PostgreSQL instance. + + + + + Execute read-only SQL queries with security validation. + + + + Execute read-only SQL queries with built-in security validation + - **Security**: Automatic validation prevents data modification + - **Use Cases**: Data exploration, reporting, analysis queries + + + + + **Security Feature**: The server operates in restricted mode by default, ensuring only read operations are permitted. + + + + +--- + +## Configuration Requirements + +### Database Connection Setup +The PostgreSQL server requires a complete connection string with authentication: + + + + ``` + postgresql://user:password@host.domain.com:5432/dbname?sslmode=require + ``` + + **Required Components:** + - **Protocol**: `postgresql://` + - **Credentials**: username and password + - **Host**: database server hostname or IP + - **Port**: database port (default: 5432) + - **Database**: target database name + - **SSL Mode**: recommended to use `sslmode=require` + + + + - **SSL/TLS**: Always use encrypted connections in production + - **User Permissions**: Grant minimum required permissions for intended operations + - **Network Access**: Ensure database is accessible from Nexus infrastructure + - **Connection Pooling**: Consider connection limits and pooling for high-traffic scenarios + + + +### Server Configuration +- **Access Mode**: Restricted (read-only with SQL validation) by default +- **Transport**: HTTP-hosted with SSE (Server-Sent Events) +- **Security**: Built-in SQL validation prevents data modification operations + + +The PostgreSQL server uses Crystal DBA's secure implementation with advanced query validation and performance optimization features. + + + +Ensure your PostgreSQL instance has the `pg_stat_statements` extension enabled for full performance monitoring capabilities. + diff --git a/nexus/reference/servers/sentry.mdx b/nexus/reference/servers/sentry.mdx new file mode 100644 index 00000000..10cfeb18 --- /dev/null +++ b/nexus/reference/servers/sentry.mdx @@ -0,0 +1,234 @@ +--- +title: "Sentry Server" +description: "Monitor and fix errors in your applications with Sentry's error tracking and performance monitoring tools" +icon: "server" +--- + +# Sentry Server + +## Overview + +The Sentry server provides comprehensive error tracking and performance monitoring capabilities. Built by [Sentry](https://sentry.io), this server enables AI assistants to access error data, manage issues, analyze performance traces, and help teams maintain healthy applications. + +## Getting Started + + + + Add the Sentry server to your Nexus environment through the server directory. + + + Connect your Sentry account using OAuth to access your organizations and projects. + + + Start with `whoami` to verify authentication and `find organizations` to see your available data. + + + +## What You Can Do + + + + Monitor, analyze, and resolve application errors and exceptions across projects + + + Analyze traces, identify bottlenecks, and optimize application performance + + + Assign issues, update status, and manage the resolution workflow + + + Create teams, find projects, and coordinate error resolution efforts + + + +## Use Cases + + + + - **Issue Analysis**: Get detailed stacktraces, error context, and affected user data + - **Root Cause Analysis**: Analyze error patterns and identify common failure points + - **Resolution Tracking**: Update issue status, assign to team members, and track fixes + - **Event Attachments**: Access screenshots, log files, and diagnostic data + + + + - **Trace Analysis**: Examine detailed performance traces and identify slow operations + - **Bottleneck Detection**: Find database queries, API calls, and operations causing delays + - **Resource Monitoring**: Track memory usage, response times, and throughput metrics + - **Trend Analysis**: Search events and perform aggregations to understand patterns + + + + - **Release Tracking**: Monitor which versions contain specific errors + - **Deployment Analysis**: Compare error rates between releases and environments + - **Version Health**: Identify problematic releases and plan rollbacks + - **Environment Comparison**: Analyze differences between staging and production + + + + - **Organization Setup**: Manage organizations and access controls + - **Team Creation**: Set up teams for different projects and responsibilities + - **Project Discovery**: Find and organize projects across your organization + - **Workflow Management**: Assign issues and track resolution progress + + + +--- + +## Available Tools (12) + + + + Essential tools for authentication and exploring your Sentry environment. + + **Account & Organization Management** + + + Identify the authenticated user and get account information + - **Use Cases**: Verify authentication, get user ID for assignments + + + List all organizations you have access to in Sentry + - **Use Cases**: Discover available organizations, get organization slugs + + + List teams within a specific organization + - **Parameters**: organizationSlug (required), regionUrl (optional) + + + List projects within a specific organization + - **Parameters**: organizationSlug (required), regionUrl (optional) + + + + + **Organization Slugs**: Found via `find_organizations`, these are required for most other operations. + + + + + Comprehensive tools for managing and resolving application issues. + + + + Get detailed information about specific issues including stacktraces and context + - **Input Methods**: Issue ID (e.g., 'PROJECT-123'), Issue URL, or event ID + - **Use Cases**: Analyze specific errors, understand failure context + + + Change issue status, assignment, and resolution state + - **Status Options**: resolved, resolvedInNextRelease, unresolved, ignored + - **Assignment**: Assign to users ('user:123') or teams ('team:456') + + + Download attachments from events (screenshots, logs, diagnostic files) + - **Parameters**: organizationSlug, projectSlug, eventId, attachmentId + - **Use Cases**: Access diagnostic data, screenshots, and log files + + + + + When updating issues, use numeric IDs for assignment (e.g., 'user:123456' or 'team:789'). + + + + + Advanced tools for performance analysis and application monitoring. + + + + Analyze performance traces with span breakdown and statistics + - **Input**: Trace ID (32-character hex string) + - **Output**: High-level overview, span details, performance metrics + + + **The primary tool for statistics and event search** - supports both aggregations and individual events + - **Aggregation Queries**: "how many errors this week", "count of timeouts" + - **Event Search**: "show me errors from last hour", "find database exceptions" + - **Natural Language**: Use plain English to describe what you're looking for + + + + + **Trace IDs**: 32-character hexadecimal strings (e.g., 'a4d1aae7216b47ff8117cf4e09ce9d0a'). + + + + + Tools for managing releases, teams, and organizational structure. + + + + List and search releases across projects + - **Parameters**: organizationSlug (required), projectSlug, query (optional) + - **Use Cases**: Find recent releases, check deployment status + + + Create new teams for organizing projects and responsibilities + - **Parameters**: organizationSlug (required), name (required) + - **Use Cases**: Set up teams for new projects, organize development efforts + + + + + **Release Management**: Use `find_releases` with query parameters to search for specific version patterns. + + + + +--- + +## Configuration Requirements + +### Authentication Setup +The Sentry server uses OAuth2 authentication with Sentry's API: + + + + 1. **OAuth Authorization**: Authenticate via Sentry's OAuth flow + 2. **Organization Access**: Ensure you have appropriate permissions in target organizations + 3. **API Permissions**: Verify your account has API access enabled + 4. **Regional URLs**: Some operations may require region-specific URLs + + + + - **Read Access**: View issues, events, traces, and project data + - **Write Access**: Update issues, create teams (if using management tools) + - **Organization Access**: Access to organizations you want to monitor + - **Project Access**: View and manage specific projects + + + +### Server Configuration +- **Transport**: HTTP-based remote server +- **Endpoint**: `https://mcp.sentry.dev/mcp` +- **Region Support**: Supports both SaaS (sentry.io) and self-hosted installations +- **API Version**: Compatible with Sentry's REST API + + +The Sentry server is hosted remotely and connects directly to Sentry's API infrastructure for optimal performance and security. + + +## Best Practices + +### Error Investigation Workflow +1. **Start with Search**: Use `search_events` with natural language queries to find relevant errors +2. **Get Issue Details**: Use `get_issue_details` for specific issues that need investigation +3. **Analyze Context**: Review stacktraces, user context, and related events +4. **Track Resolution**: Use `update_issue` to assign, resolve, or prioritize issues + +### Performance Monitoring +1. **Trace Analysis**: Use `get_trace_details` for specific slow requests or transactions +2. **Pattern Detection**: Use `search_events` for performance aggregations and trends +3. **Release Comparison**: Compare performance across releases using `find_releases` +4. **Bottleneck Identification**: Focus on spans with high duration or error rates + +### Team Collaboration +1. **Organization Setup**: Use `find_organizations` and `find_teams` to understand structure +2. **Project Discovery**: Use `find_projects` to map applications and ownership +3. **Issue Assignment**: Use `update_issue` with team assignments for collaborative resolution +4. **Status Tracking**: Maintain clear issue status to track resolution progress + + +Always verify organization and project slugs using the discovery tools before performing operations on specific resources. + diff --git a/nexus/reference/servers/slack.mdx b/nexus/reference/servers/slack.mdx new file mode 100644 index 00000000..16dd827a --- /dev/null +++ b/nexus/reference/servers/slack.mdx @@ -0,0 +1,121 @@ +--- +title: Slack +description: Connect to Slack workspaces to read and send messages, manage channels, and interact with users +icon: "server" +--- + +## Overview + +The Slack server enables AI assistants to interact with your [Slack](https://slack.com) workspaces, allowing seamless communication, channel management, and team collaboration through conversational AI. + +## How to Add Slack + + + + 1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) + 2. Click **Create New App** + 3. Select **From scratch** + 4. Name your app and select your workspace + + + 1. In your app settings, click **OAuth & Permissions** in the left menu + 2. Under **Scopes > Bot Token Scopes**, add all required access permissions + 3. Scroll up and click **Install to [workspace]** + 4. Copy the **Bot User OAuth Token** that appears + + + 1. Add the Slack server to your Nexus environment through the server directory + 2. Paste your **Bot User OAuth Token** in the Slack settings in Nexus + + + Start with a simple command like `list channels` or `get recent messages from #general` to verify the connection works properly. + + + + +If you have difficulty prompting the bot to update OAuth token, go to **Nexus > Org & Toolkit > Account**, delete Slack, then re-add the Slack server to get the prompt again. + + +## What You Can Do + + + + Send messages, reply to threads, and interact with team members across channels + + + List channels, browse conversations, and access channel history + + + Get user profiles, add reactions, and engage with workspace members + + + Reply to message threads and retrieve threaded conversations + + + +## Available Tools + +### Communication Tools + + + + `slack_post_message` — Post a new message to a Slack channel + + + + `slack_reply_to_thread` — Reply to a specific message thread in Slack + + + + `slack_add_reaction` — Add a reaction emoji to a message + + + +### Channel Management + + + + `slack_list_channels` — List public or pre-defined channels in the workspace with pagination + + + + `slack_get_channel_history` — Get recent messages from a channel + + + + `slack_get_thread_replies` — Get all replies in a message thread + + + +### User Management + + + + `slack_get_users` — Get a list of all users in the workspace with their basic profile information + + + + `slack_get_user_profile` — Get detailed profile information for a specific user + + + +## Use Cases + +### Team Collaboration +- **Daily Standups**: "Post our team standup summary to #engineering" +- **Project Updates**: "Reply to the latest message in #project-alpha with our status update" +- **Announcements**: "Send a message to #general about the deployment completion" + +### Communication Management +- **Message Monitoring**: "Show me the last 20 messages from #support" +- **Thread Following**: "Get all replies in the thread about the database issue" +- **Team Engagement**: "Add a ✅ reaction to the latest message in #deployment" + +### Team Insights +- **User Discovery**: "List all users in the workspace" +- **Profile Lookup**: "Get John's profile information" +- **Channel Overview**: "Show me all available channels" + + +The Slack server requires appropriate workspace permissions and bot token configuration to access channels and send messages. + diff --git a/nexus/troubleshooting.mdx b/nexus/troubleshooting.mdx new file mode 100644 index 00000000..a56f8bf8 --- /dev/null +++ b/nexus/troubleshooting.mdx @@ -0,0 +1,292 @@ +--- +title: Troubleshooting +description: Solutions for common Civic Nexus setup and connection issues +icon: "wrench" +--- + +## Primary Client Issues (ChatGPT & Claude) + +### 401 Authentication Errors + + + + **Symptoms:** "Unauthorized", "Authentication failed", or "Invalid credentials" when adding MCP connector + + **For Claude Desktop/Claude.ai:** + - Ensure you have Claude Pro, Team, or Enterprise (MCP not available on free plan) + - Check that you're signed into your Claude account + - Remove and re-add the Civic Nexus connector with fresh URL + - Clear browser cache and cookies for claude.ai + - Verify the MCP URL is correct: `https://nexus.civic.com/hub/mcp` + + **For ChatGPT (when available):** + - Ensure you have ChatGPT Plus or Enterprise + - Check that MCP connectors are enabled in your subscription + - Clear browser cache for chatgpt.com + - Try incognito/private browsing mode + + + + **Symptoms:** Connector connects but tools return "Unauthorized" errors + + **Solutions:** + - Visit [nexus.civic.com](https://nexus.civic.com) and ensure you've authorized the specific services (GitHub, Slack, etc.) + - Check that your service accounts haven't revoked access + - Re-authorize individual services: ask your AI "Connect me to GitHub" + - Verify you have the required permissions (repo access, workspace membership, etc.) + + + +### 404 Not Found Errors + + + + **Symptoms:** "Connector not found", "Invalid URL", or "Service unavailable" when adding connector + + **Solutions:** + - Double-check the MCP URL is exactly: `https://nexus.civic.com/hub/mcp` + - Ensure you have created an account at [nexus.civic.com](https://nexus.civic.com) + - Check your internet connection and try again + - Corporate firewall may be blocking - try from personal network + - Wait a few minutes and retry (temporary service issues) + + + + **Symptoms:** Connector works but specific tools return "Not Found" errors + + **Solutions:** + - Check that you selected the required MCP servers at nexus.civic.com + - Some tools require specific service permissions - re-authorize the service + - Try asking: "What MCP servers are available?" to see current connections + - Service may be temporarily unavailable - try again later + + + +### Connection Issues + + + + **Symptoms:** Civic Nexus connector shows "Disconnected" or "Failed" status + + **Solutions:** + - Check internet connection and try refreshing + - Remove and re-add the connector with the correct URL + - Ensure no VPN or proxy is interfering + - For Claude Desktop: update to latest version + - For Claude.ai: try refreshing the browser page + + + + **Symptoms:** Client tries to connect but no auth window appears + + **Solutions:** + - Allow popups for your client (Claude Desktop/ChatGPT) + - Try connecting from a different network (corporate firewalls may block) + - Clear client cache/settings and re-add the connector + - Use incognito/private browsing mode for web clients + + + + **Symptoms:** Connection succeeds but no MCP tools are visible + + **Solutions:** + - Restart your client completely after initial setup + - Check nexus.civic.com - make sure you selected MCP servers + - Ask your AI: "What MCP tools are available?" to verify connection + - Complete OAuth flows for each service you want to use + + + +## Authentication Issues + + + + **Symptoms:** Keep getting asked to sign in despite successful authentication + + **Solutions:** + - Check system clock is accurate (OAuth tokens are time-sensitive) + - Clear browser cookies for civic.com and nexus.civic.com + - Remove and re-add the connector in your client + + + + **Symptoms:** "Invalid scope", "Access denied", or "Token expired" for GitHub/Slack/etc. + + **Solutions:** + - Revisit nexus.civic.com and re-authorize the specific service + - Check service account permissions (e.g., GitHub org access, Slack workspace admin) + - Some services require re-authorization after permission changes + - Token may have been revoked - re-authorize to generate new one + + + + **Symptoms:** "Unauthorized" or "Forbidden" errors when using MCP commands + + **Solutions:** + - Service tokens may have expired - re-authorize at nexus.civic.com + - Check rate limits - wait a few minutes and try again + - Verify you have required permissions (repo access, channel membership, etc.) + - Contact admin if using workspace/organization accounts + + + +## Performance Issues + + + + **Symptoms:** MCP commands take a long time to complete + + **Solutions:** + - First request to each service is slower (authentication) + - Large operations (file uploads, bulk queries) are inherently slow + - Check network connection - corporate proxies can add latency + + + + **Symptoms:** Commands fail with timeout errors + + **Solutions:** + - Break large requests into smaller chunks + - Some services have strict rate limits (GitHub API: 5,000/hour) + - Try the same command later - may be temporary service issues + + + +## Client-Specific Issues + +### Claude Desktop + + + + **Solutions:** + - Update Claude Desktop to latest version + - Remove connector and re-add with fresh MCP URL + - Check macOS system preferences allow Claude network access + + + + **Symptoms:** Claude shows connected but can't access your tools, or tools are missing + + **Solutions:** + 1. **Check connector status:** In Claude Desktop settings, verify Civic Nexus connector shows "Connected" + 2. **Verify tool access:** Ask Claude "What MCP tools are available?" to see current tools + 3. **Reauthorize if needed:** If tools are missing: + - Go to Claude Desktop → Settings → Connectors + - Find Civic Nexus connector and click on it + - If prompted to "Connect" or "Authorize", click it to reauthorize + - Complete any OAuth flows that appear + 4. **Restart Claude:** Close and reopen Claude Desktop after reauthorization + 5. **Test again:** Try using a simple tool command to verify access + + + +### Cursor + + + + **Solutions:** + - Restart Cursor completely (not just reload window) + - Check Cursor Settings → Features → MCP is enabled + - Try disabling and re-enabling Civic Nexus in MCP settings + - Update Cursor to latest version + + + +### VS Code + + + + **Solutions:** + - Install or update the MCP extension from VS Code marketplace + - Check VS Code settings: search "MCP" and enable required features + - Reload VS Code window after MCP configuration changes + - Verify extension has proper permissions + + + +## Corporate Network Issues + +Many issues stem from corporate security policies: + + +**Common corporate restrictions that affect Nexus:** +- Proxy servers intercepting HTTPS requests +- TLS certificate inspection causing SSL errors +- OAuth redirect URLs blocked by content filters + + +**Solutions:** +- Work with IT to whitelist `*.civic.com` +- Try initial setup from personal network, then switch to corporate +- Request proxy bypass for MCP connectors +- Use company VPN if external setup works + +## Getting Help + +### Before Contacting Support + +Gather this information to speed up resolution: + + + + - Operating system and version + - Client type and version + + + - What error messages do you see? + - When did the issue start? + - Which client are you using? + + + - Updated any software recently? + - Changed network or VPN settings? + - New corporate security policies? + + + +### Contact Support + + + Include your system info and error details for faster resolution + + + +**Join our Slack community** for the latest updates, improvements, and real-time help from other users. We regularly share troubleshooting tips and new features there. + + +## Advanced Debugging + +### Enable Debug Logging + +Check your client's documentation for MCP debug/verbose logging options. Most clients support enabling verbose or debug mode for MCP connections. + +### Network Debugging + +Test connectivity to Nexus services: + +```bash +# Test basic connectivity +curl -I https://nexus.civic.com + +# Test MCP endpoint (should return 405 Method Not Allowed - that's correct) +curl -I https://nexus.civic.com/hub/mcp +``` + +### Reset Everything + +If nothing else works, complete reset: + + + + Remove Civic Nexus connector from client + + + Clear cookies/data for civic.com and nexus.civic.com + + + Restart client and browser + + + Start setup process from the beginning + +