Add USE MCP documentation and update Sources docs
- New keyword-use-mcp.md: Complete docs for USE MCP keyword and mcp.csv - Updated sources.md: MCP Servers section with mcp.csv configuration - CSV format examples and connection type documentation - Authentication configuration (api_key, bearer) - Integration with Tasks and BASIC examples
This commit is contained in:
parent
89eef18cf6
commit
25355f7066
2 changed files with 702 additions and 289 deletions
|
|
@ -1,182 +1,376 @@
|
|||
# Sources - Prompts & Templates
|
||||
# Sources
|
||||
|
||||
> **Your bot configuration hub**
|
||||
|
||||
<img src="../../assets/suite/sources-screen.svg" alt="Sources Interface Screen" style="max-width: 100%; height: auto;">
|
||||
> **Repositories, Apps, Prompts, Templates & MCP Servers**
|
||||
|
||||
---
|
||||
|
||||
<img src="../../assets/chapter-04/sources-interface.svg" alt="Sources Interface" style="max-width: 100%; height: auto;">
|
||||
|
||||
## Overview
|
||||
|
||||
Sources is the configuration center in General Bots Suite. Manage your bots, prompts, templates, and knowledge bases all in one place. Sources is where you create new bots, customize their behavior, and organize the content that powers your AI assistant.
|
||||
Sources is where you connect everything your bot can reference. Add Git repositories, manage generated apps, configure prompts, and connect MCP servers. Most importantly, Sources enables **@mentions** in chat—reference `@botserver` to work on a repository or `@myapp` to modify an app you created.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
## Tabs
|
||||
|
||||
### Managing Bots
|
||||
| Tab | What It Contains |
|
||||
|-----|------------------|
|
||||
| **Repositories** | Git repos (GitHub, GitLab, Bitbucket) |
|
||||
| **Apps** | HTMX apps created with CREATE SITE |
|
||||
| **Prompts** | System prompts and templates |
|
||||
| **Templates** | Bot packages (.gbai) |
|
||||
| **News** | Platform updates and announcements |
|
||||
| **MCP Servers** | Model Context Protocol servers |
|
||||
| **LLM Tools** | Available LLM-invokable tools |
|
||||
| **Models** | Configured AI models |
|
||||
|
||||
#### Creating a New Bot
|
||||
---
|
||||
|
||||
1. Click **+ New Bot** in the top right
|
||||
2. Fill in the bot details:
|
||||
## Repositories
|
||||
|
||||
Connect Git repositories so Tasks can read, modify, and commit code.
|
||||
|
||||
### Adding a Repository
|
||||
|
||||
1. Click **+ Add Repository**
|
||||
2. Enter the repository URL (HTTPS or SSH)
|
||||
3. Authenticate if private
|
||||
4. Click **Connect**
|
||||
|
||||
### Repository Card
|
||||
|
||||
Each connected repository shows:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Bot ID** | Unique identifier (lowercase, numbers, hyphens only) |
|
||||
| **Display Name** | User-friendly name shown in chat |
|
||||
| **Description** | Brief explanation of what the bot does |
|
||||
| **Start from** | Blank, Template, or Clone existing |
|
||||
| **Name** | Repository name with @mention tag |
|
||||
| **Owner** | Organization or user |
|
||||
| **Description** | From repository README |
|
||||
| **Language** | Primary programming language |
|
||||
| **Stars/Forks** | GitHub metrics |
|
||||
| **Status** | Connected or disconnected |
|
||||
|
||||
#### Bot Settings
|
||||
### Using @mentions with Repositories
|
||||
|
||||
Click the **⚙️** icon on any bot to configure:
|
||||
In chat, type `@` followed by the repo name:
|
||||
|
||||
**General Settings:**
|
||||
```
|
||||
You: @botserver add error handling to the login function
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| **Display Name** | Name shown to users |
|
||||
| **Welcome Message** | First message when conversation starts |
|
||||
| **Language** | Primary language for the bot |
|
||||
| **Timezone** | Bot's timezone for date/time operations |
|
||||
| **Status** | Live, Draft, or Maintenance |
|
||||
|
||||
**Status Options:**
|
||||
- **Live** - Bot is active and responding
|
||||
- **Draft** - Bot is hidden from users
|
||||
- **Maintenance** - Shows maintenance message
|
||||
|
||||
#### AI Settings
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| **Provider** | AI provider (OpenAI, Azure, etc.) |
|
||||
| **Model** | Model to use (GPT-5, Claude Sonnet 4.5, local GGUF, etc.) |
|
||||
| **Temperature** | Creativity level (0 = focused, 1 = creative) |
|
||||
| **Max Tokens** | Maximum response length |
|
||||
| **System Prompt** | Bot personality and instructions |
|
||||
| **Knowledge Base** | Connected .gbkb for answers |
|
||||
|
||||
---
|
||||
|
||||
### Managing Prompts
|
||||
|
||||
Prompts are reusable text templates for AI interactions.
|
||||
|
||||
**Prompt Types:**
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| **System Prompt** | Bot personality/behavior |
|
||||
| **Task Prompt** | Specific task instructions |
|
||||
| **Template** | Reusable text with variables |
|
||||
|
||||
**Creating a Prompt:**
|
||||
|
||||
1. Click **+ New Prompt**
|
||||
2. Enter a name (e.g., "support-agent")
|
||||
3. Select type
|
||||
4. Write prompt content with optional `{{variables}}`
|
||||
5. Save and link to bots
|
||||
|
||||
**Example Prompt:**
|
||||
|
||||
```botserver/docs/src/chapter-04-gbui/apps/sources-prompt-example.txt
|
||||
You are a friendly and professional customer support agent
|
||||
for {{company_name}}.
|
||||
|
||||
## Your Personality
|
||||
- Be warm and empathetic
|
||||
- Use simple, clear language
|
||||
- Be patient and thorough
|
||||
|
||||
## Guidelines
|
||||
- Always verify customer identity before sharing account info
|
||||
- If unsure, search the knowledge base
|
||||
- Escalate complex issues to human agents
|
||||
- Never make promises about refunds or compensation
|
||||
Bot: I'll modify botserver. Looking at the login function...
|
||||
[Task created: Add error handling to login]
|
||||
```
|
||||
|
||||
---
|
||||
The system will:
|
||||
1. Clone or pull the latest code
|
||||
2. Analyze the relevant files
|
||||
3. Make the requested changes
|
||||
4. Create a commit or pull request
|
||||
|
||||
### Managing Templates
|
||||
### Repository Actions
|
||||
|
||||
Templates are pre-built bot packages you can reuse.
|
||||
|
||||
**Installed Templates:**
|
||||
|
||||
| Template | Description |
|
||||
|----------|-------------|
|
||||
| **📋 CRM** | Full CRM with leads, contacts |
|
||||
| **📋 Support** | Ticket management and customer service |
|
||||
| **📋 FAQ** | Answer common questions from KB |
|
||||
|
||||
**Available Templates:**
|
||||
|
||||
| Template | Description |
|
||||
|----------|-------------|
|
||||
| **📋 HR** | Employee self-service |
|
||||
| **📋 Analytics** | Dashboard and metrics |
|
||||
| **📋 Compliance** | LGPD, GDPR compliance |
|
||||
|
||||
**Template Contents:**
|
||||
|
||||
Templates include:
|
||||
- Dialog scripts (.bas files)
|
||||
- Bot configuration
|
||||
- Knowledge base documentation
|
||||
- Sample conversations
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| **Browse** | View files and folders |
|
||||
| **Mention** | Insert @repo into chat |
|
||||
| **Disconnect** | Remove from Sources |
|
||||
| **Settings** | Configure branch, credentials |
|
||||
|
||||
---
|
||||
|
||||
### Managing Knowledge Bases
|
||||
## Apps
|
||||
|
||||
Knowledge bases store documents that your bot can search for answers.
|
||||
Apps are HTMX applications created with `CREATE SITE`. They appear here automatically.
|
||||
|
||||
### App Card
|
||||
|
||||
Each app shows:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Documents** | Count of uploaded files |
|
||||
| **Size** | Total storage used |
|
||||
| **Last Indexed** | When content was last processed |
|
||||
| **Used By** | Bots connected to this KB |
|
||||
| **Name** | App name with @mention tag |
|
||||
| **Type** | HTMX, Dashboard, Site |
|
||||
| **Description** | Generated from creation prompt |
|
||||
| **URL** | Live endpoint (e.g., `/crm`) |
|
||||
| **Created** | When the app was generated |
|
||||
|
||||
**Uploading Documents:**
|
||||
### Using @mentions with Apps
|
||||
|
||||
1. Open the knowledge base
|
||||
2. Click **Upload** or drag files
|
||||
3. Organize into folders
|
||||
4. Click **Reindex** to process new content
|
||||
Reference apps to modify them:
|
||||
|
||||
**Supported Formats:**
|
||||
- PDF, DOCX, TXT, MD
|
||||
- CSV, XLSX
|
||||
- HTML, JSON
|
||||
```
|
||||
You: @crm change the submit button to green
|
||||
|
||||
Bot: I'll update the CRM app. Modifying the button styles...
|
||||
[Task created: Change submit button color]
|
||||
```
|
||||
|
||||
```
|
||||
You: @dashboard add a new KPI card for monthly revenue
|
||||
|
||||
Bot: I'll add that to your dashboard. Creating the KPI card...
|
||||
[Task created: Add monthly revenue KPI]
|
||||
```
|
||||
|
||||
### App Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| **Open** | View app in new tab |
|
||||
| **Edit** | Open Tasks with app context |
|
||||
| **Mention** | Insert @app into chat |
|
||||
| **Delete** | Remove app and files |
|
||||
|
||||
---
|
||||
|
||||
## Import and Export
|
||||
## @Mention Autocomplete
|
||||
|
||||
### Exporting a Bot
|
||||
When typing in chat, `@` triggers autocomplete:
|
||||
|
||||
1. Click **⚙️** on the bot
|
||||
2. Select **Export**
|
||||
3. Choose what to include:
|
||||
- Bot configuration
|
||||
- Dialog scripts (.bas files)
|
||||
- Prompts
|
||||
- Knowledge base (optional, large)
|
||||
- Conversation history (optional)
|
||||
4. Select format: .gbai, ZIP, or JSON
|
||||
1. Type `@` to see suggestions
|
||||
2. Continue typing to filter (e.g., `@bot` shows `@botserver`, `@botui`)
|
||||
3. Press **Enter** or **Tab** to select
|
||||
4. Press **Escape** to cancel
|
||||
|
||||
### Importing a Bot
|
||||
### Mention Types
|
||||
|
||||
1. Click **Import** at the top
|
||||
2. Drop file or browse (supported: .gbai, .zip)
|
||||
3. Choose:
|
||||
- Create new bot, or
|
||||
- Replace existing bot
|
||||
4. Configure merge options for prompts and KB
|
||||
| Type | Icon | Example |
|
||||
|------|------|---------|
|
||||
| Repository | Git icon | `@botserver` |
|
||||
| App | Grid icon | `@mycrm` |
|
||||
|
||||
### Context for Tasks
|
||||
|
||||
When you mention a source, it becomes context for the task:
|
||||
|
||||
```
|
||||
You: @botserver @botui make the API response format consistent
|
||||
|
||||
Bot: I'll update both repositories to use consistent response formats.
|
||||
[Task created with context: botserver, botui]
|
||||
```
|
||||
|
||||
Without explicit mentions, Tasks uses recent context or asks for clarification.
|
||||
|
||||
---
|
||||
|
||||
## Prompts
|
||||
|
||||
System prompts define bot personality and behavior.
|
||||
|
||||
### Prompt Categories
|
||||
|
||||
| Category | Purpose |
|
||||
|----------|---------|
|
||||
| **Assistants** | Role-specific personas |
|
||||
| **Tools** | Tool descriptions for LLM |
|
||||
| **Personas** | Bot personality definitions |
|
||||
| **Custom** | Your own prompts |
|
||||
|
||||
### Creating a Prompt
|
||||
|
||||
1. Click **+ New Prompt**
|
||||
2. Enter name and category
|
||||
3. Write prompt content
|
||||
4. Use `{{variables}}` for dynamic values
|
||||
5. Click **Save**
|
||||
|
||||
### Prompt Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| **Use** | Apply to current session |
|
||||
| **Copy** | Copy to clipboard |
|
||||
| **Save** | Add to collection |
|
||||
| **Edit** | Modify content |
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
Bot packages ready to deploy.
|
||||
|
||||
### Available Templates
|
||||
|
||||
| Template | Description |
|
||||
|----------|-------------|
|
||||
| **CRM** | Customer relationship management |
|
||||
| **Support** | Helpdesk and ticketing |
|
||||
| **Analytics** | Dashboards and reports |
|
||||
| **Compliance** | LGPD, GDPR, HIPAA |
|
||||
|
||||
### Installing a Template
|
||||
|
||||
1. Click on template card
|
||||
2. Review contents
|
||||
3. Click **Install**
|
||||
4. Configure settings
|
||||
5. Bot is ready
|
||||
|
||||
---
|
||||
|
||||
## MCP Servers
|
||||
|
||||
Model Context Protocol servers extend bot capabilities. MCP servers are configured via `mcp.csv` in the bot's `.gbai` folder, making their tools available to Tasks just like BASIC keywords.
|
||||
|
||||
### The mcp.csv File
|
||||
|
||||
MCP servers are configured by adding entries to `mcp.csv` in your bot's `.gbai` folder:
|
||||
|
||||
```
|
||||
mybot.gbai/
|
||||
├── mybot.gbdialog/ # BASIC scripts
|
||||
├── mybot.gbdrive/ # Files and documents
|
||||
├── config.csv # Bot configuration
|
||||
├── attendant.csv # Attendant configuration
|
||||
└── mcp.csv # MCP server definitions
|
||||
```
|
||||
|
||||
When botserver starts, it reads the `mcp.csv` file and loads all server configurations.
|
||||
|
||||
### Server Card
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Name** | Server identifier (used for `USE MCP` calls) |
|
||||
| **Type** | filesystem, github, database, slack, etc. |
|
||||
| **Status** | Active, Inactive, Error |
|
||||
| **Tools** | Available tools count |
|
||||
| **Source** | "directory" (from .gbmcp) |
|
||||
|
||||
### mcp.csv Format
|
||||
|
||||
The CSV file has the following columns:
|
||||
|
||||
| Column | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| `name` | Yes | Unique server identifier |
|
||||
| `type` | Yes | Connection type: `stdio`, `http`, `websocket`, `tcp` |
|
||||
| `command` | Yes | For stdio: command. For http/ws: URL |
|
||||
| `args` | No | Command arguments (space-separated) |
|
||||
| `description` | No | Human-readable description |
|
||||
| `enabled` | No | `true` or `false` (default: `true`) |
|
||||
| `auth_type` | No | `none`, `api_key`, `bearer` |
|
||||
| `auth_env` | No | Environment variable for auth |
|
||||
|
||||
### Example mcp.csv
|
||||
|
||||
```csv
|
||||
name,type,command,args,description,enabled
|
||||
# MCP Server Configuration - lines starting with # are comments
|
||||
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",Access local files,true
|
||||
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub API,true,bearer,GITHUB_TOKEN
|
||||
postgres,stdio,npx,"-y @modelcontextprotocol/server-postgres",Database queries,false
|
||||
slack,stdio,npx,"-y @modelcontextprotocol/server-slack",Slack messaging,true,bearer,SLACK_BOT_TOKEN
|
||||
myapi,http,https://api.example.com/mcp,,Custom API,true,api_key,MY_API_KEY
|
||||
```
|
||||
|
||||
### Adding an MCP Server
|
||||
|
||||
**Method 1: Via UI**
|
||||
1. Click **+ Add Server**
|
||||
2. Enter server details
|
||||
3. Configure connection type (stdio, http, websocket)
|
||||
4. Test connection
|
||||
5. Click **Save**
|
||||
|
||||
**Method 2: Via mcp.csv**
|
||||
1. Open `mcp.csv` in your `.gbai` folder
|
||||
2. Add a new line with server configuration
|
||||
3. Restart bot or click **🔄 Reload** in Sources UI
|
||||
4. Server appears automatically
|
||||
|
||||
### Using MCP Tools in BASIC
|
||||
|
||||
```bas
|
||||
' Read a file using filesystem MCP server
|
||||
content = USE MCP "filesystem", "read_file", {"path": "/data/config.json"}
|
||||
|
||||
' Query database
|
||||
results = USE MCP "postgres", "query", {"sql": "SELECT * FROM users"}
|
||||
|
||||
' Send Slack message
|
||||
USE MCP "slack", "send_message", {"channel": "#general", "text": "Hello!"}
|
||||
```
|
||||
|
||||
### Connection Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| **stdio** | Local process (npx, node, python) |
|
||||
| **http** | REST API endpoint |
|
||||
| **websocket** | WebSocket connection |
|
||||
| **tcp** | Raw TCP socket |
|
||||
|
||||
### Popular MCP Servers
|
||||
|
||||
| Server | Package | Description |
|
||||
|--------|---------|-------------|
|
||||
| Filesystem | `@modelcontextprotocol/server-filesystem` | File operations |
|
||||
| GitHub | `@modelcontextprotocol/server-github` | GitHub API |
|
||||
| PostgreSQL | `@modelcontextprotocol/server-postgres` | Database queries |
|
||||
| Slack | `@modelcontextprotocol/server-slack` | Messaging |
|
||||
|
||||
See [USE MCP](../../06-gbdialog/keyword-use-mcp.md) for complete documentation.
|
||||
|
||||
---
|
||||
|
||||
## LLM Tools
|
||||
|
||||
Tools that the LLM can invoke during conversations.
|
||||
|
||||
### Tool Sources
|
||||
|
||||
| Source | Description |
|
||||
|--------|-------------|
|
||||
| **Built-in** | Core BASIC keywords |
|
||||
| **MCP** | From connected MCP servers |
|
||||
| **Custom** | Your .bas files with DESCRIPTION |
|
||||
|
||||
### Tool Card
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Name** | Tool identifier |
|
||||
| **Description** | What it does |
|
||||
| **Parameters** | Required inputs |
|
||||
| **Source** | Where it comes from |
|
||||
|
||||
---
|
||||
|
||||
## Models
|
||||
|
||||
Configured AI models for the platform.
|
||||
|
||||
### Model Card
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Name** | Model identifier |
|
||||
| **Provider** | OpenAI, Anthropic, Local, etc. |
|
||||
| **Status** | Active, coming soon |
|
||||
| **Tags** | Capabilities (chat, code, vision) |
|
||||
|
||||
### Supported Providers
|
||||
|
||||
| Provider | Models |
|
||||
|----------|--------|
|
||||
| **OpenAI** | GPT-4, GPT-4o |
|
||||
| **Anthropic** | Claude Sonnet 4.5, Claude Opus 4 |
|
||||
| **Local** | llama.cpp GGUF models |
|
||||
| **Azure** | Azure OpenAI deployments |
|
||||
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
Use the search box to find across all source types:
|
||||
|
||||
- Type to search by name
|
||||
- Results update as you type
|
||||
- Press **Enter** to search
|
||||
- Press **Escape** to clear
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -184,165 +378,40 @@ Knowledge bases store documents that your bot can search for answers.
|
|||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+N` | New bot |
|
||||
| `Ctrl+S` | Save changes |
|
||||
| `Ctrl+E` | Export selected |
|
||||
| `Ctrl+I` | Import |
|
||||
| `Delete` | Delete selected |
|
||||
| `Ctrl+D` | Duplicate |
|
||||
| `F2` | Rename |
|
||||
| `/` | Search |
|
||||
| `Ctrl+K` | Focus search |
|
||||
| `1-6` | Switch tabs |
|
||||
| `Escape` | Close modal |
|
||||
| `Enter` | Open selected |
|
||||
| `Escape` | Close dialog |
|
||||
|
||||
---
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
### Bot Management
|
||||
|
||||
💡 **Use descriptive names** - "customer-support-v2" is better than "bot1"
|
||||
|
||||
💡 **Keep prompts separate** - Reuse prompts across multiple bots
|
||||
|
||||
💡 **Version your exports** - Export before major changes
|
||||
|
||||
💡 **Test in Draft mode** - Don't go Live until fully tested
|
||||
|
||||
### Prompt Writing
|
||||
|
||||
💡 **Be specific** - Clear instructions give better results
|
||||
|
||||
💡 **Use examples** - Show the AI what good responses look like
|
||||
|
||||
💡 **Set boundaries** - Define what the bot should NOT do
|
||||
|
||||
💡 **Use variables** - Make prompts reusable with {{placeholders}}
|
||||
|
||||
### Knowledge Base
|
||||
|
||||
💡 **Organize in folders** - Group related documents together
|
||||
|
||||
💡 **Keep documents current** - Remove outdated information
|
||||
|
||||
💡 **Use clear filenames** - "refund-policy-2025.pdf" not "doc1.pdf"
|
||||
|
||||
💡 **Reindex after changes** - New content isn't searchable until indexed
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot not responding
|
||||
|
||||
**Possible causes:**
|
||||
1. Bot is in Draft mode
|
||||
2. AI provider not configured
|
||||
3. No dialogs or prompts set up
|
||||
|
||||
**Solution:**
|
||||
1. Check bot status is "Live"
|
||||
2. Verify AI settings have valid API key
|
||||
3. Ensure at least start.bas exists
|
||||
4. Check error logs in Analytics
|
||||
|
||||
---
|
||||
|
||||
### Knowledge base not finding answers
|
||||
|
||||
**Possible causes:**
|
||||
1. Documents not indexed
|
||||
2. Document format not supported
|
||||
3. Query doesn't match content
|
||||
|
||||
**Solution:**
|
||||
1. Click "Reindex" and wait for completion
|
||||
2. Convert documents to supported formats
|
||||
3. Check document actually contains the information
|
||||
4. Try different phrasing
|
||||
|
||||
---
|
||||
|
||||
### Import fails
|
||||
|
||||
**Possible causes:**
|
||||
1. File corrupted
|
||||
2. Incompatible version
|
||||
3. Duplicate bot ID
|
||||
|
||||
**Solution:**
|
||||
1. Try re-exporting from source
|
||||
2. Check General Bots version compatibility
|
||||
3. Choose "Create new bot" instead of replace
|
||||
4. Rename bot ID if duplicate
|
||||
|
||||
---
|
||||
|
||||
### Prompts not applying
|
||||
|
||||
**Possible causes:**
|
||||
1. Prompt not linked to bot
|
||||
2. Variable not defined
|
||||
3. Syntax error in prompt
|
||||
|
||||
**Solution:**
|
||||
1. Check AI Settings → System Prompt selection
|
||||
2. Verify all {{variables}} have values
|
||||
3. Test prompt with "Test" button
|
||||
4. Check for unclosed brackets or quotes
|
||||
|
||||
---
|
||||
|
||||
## BASIC Integration
|
||||
|
||||
Access Sources data from dialogs:
|
||||
### List Repositories
|
||||
|
||||
### Get Bot Configuration
|
||||
|
||||
```botserver/docs/src/chapter-04-gbui/apps/sources-config.basic
|
||||
config = GET BOT CONFIG
|
||||
TALK "Bot name: " + config.displayName
|
||||
TALK "Language: " + config.language
|
||||
```bas
|
||||
repos = GET REPOSITORIES
|
||||
FOR EACH repo IN repos
|
||||
TALK repo.name + " - " + repo.description
|
||||
NEXT
|
||||
```
|
||||
|
||||
### Use Prompts
|
||||
### List Apps
|
||||
|
||||
```botserver/docs/src/chapter-04-gbui/apps/sources-prompts.basic
|
||||
' Load a prompt template
|
||||
prompt = GET PROMPT "summarize"
|
||||
|
||||
' Use with variables
|
||||
summary = GENERATE WITH PROMPT prompt, content
|
||||
TALK summary
|
||||
```bas
|
||||
apps = GET APPS
|
||||
FOR EACH app IN apps
|
||||
TALK app.name + " at /" + app.url
|
||||
NEXT
|
||||
```
|
||||
|
||||
### Search Knowledge Base
|
||||
### Get Task Context
|
||||
|
||||
```botserver/docs/src/chapter-04-gbui/apps/sources-search.basic
|
||||
HEAR question AS TEXT "What would you like to know?"
|
||||
|
||||
results = SEARCH KB question IN "support.gbkb"
|
||||
|
||||
IF COUNT(results) > 0 THEN
|
||||
TALK results[0].answer
|
||||
TALK "Source: " + results[0].source
|
||||
ELSE
|
||||
TALK "I couldn't find information about that."
|
||||
END IF
|
||||
```
|
||||
|
||||
### List Available Bots
|
||||
|
||||
```botserver/docs/src/chapter-04-gbui/apps/sources-list.basic
|
||||
bots = GET BOTS
|
||||
|
||||
TALK "Available bots:"
|
||||
FOR EACH bot IN bots
|
||||
IF bot.status = "live" THEN
|
||||
TALK "● " + bot.displayName
|
||||
ELSE
|
||||
TALK "○ " + bot.displayName + " (draft)"
|
||||
END IF
|
||||
```bas
|
||||
' Get sources mentioned in current conversation
|
||||
context = GET TASK CONTEXT
|
||||
FOR EACH source IN context
|
||||
TALK "Working with: @" + source.name
|
||||
NEXT
|
||||
```
|
||||
|
||||
|
|
@ -350,7 +419,6 @@ NEXT
|
|||
|
||||
## See Also
|
||||
|
||||
- [Designer App](./designer.md) - Visual flow builder
|
||||
- [Drive App](./drive.md) - Upload KB documents
|
||||
- [How To: Create Your First Bot](../how-to/create-first-bot.md)
|
||||
- [How To: Add Documents to Knowledge Base](../how-to/add-kb-documents.md)
|
||||
- [Tasks](./tasks.md) - Execute work on repositories and apps
|
||||
- [Chat](./chat.md) - Use @mentions in conversation
|
||||
- [Autonomous Task AI](../../07-gbapp/autonomous-tasks.md) - How context flows to tasks
|
||||
345
src/06-gbdialog/keyword-use-mcp.md
Normal file
345
src/06-gbdialog/keyword-use-mcp.md
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
# USE MCP
|
||||
|
||||
> **Invoke MCP Server Tools from BASIC**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The `USE MCP` keyword allows you to invoke tools from Model Context Protocol (MCP) servers directly in your BASIC scripts. MCP servers extend your bot's capabilities by providing access to external systems like databases, filesystems, APIs, and more.
|
||||
|
||||
---
|
||||
|
||||
## Syntax
|
||||
|
||||
```bas
|
||||
result = USE MCP "server_name", "tool_name", {parameters}
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `server_name` | Name of the MCP server (as defined in `mcp.csv`) |
|
||||
| `tool_name` | Name of the tool to invoke |
|
||||
| `parameters` | JSON object with tool parameters |
|
||||
|
||||
---
|
||||
|
||||
## The mcp.csv File
|
||||
|
||||
MCP servers are configured by adding entries to the `mcp.csv` file in your bot's `.gbai` folder:
|
||||
|
||||
```
|
||||
mybot.gbai/
|
||||
├── mybot.gbdialog/ # BASIC scripts
|
||||
├── mybot.gbdrive/ # Files and documents
|
||||
├── config.csv # Bot configuration
|
||||
├── attendant.csv # Attendant configuration
|
||||
└── mcp.csv # MCP server definitions
|
||||
```
|
||||
|
||||
When botserver starts, it reads the `mcp.csv` file and loads all server configurations. These servers become available to Tasks and can be invoked using the `USE MCP` keyword.
|
||||
|
||||
---
|
||||
|
||||
## mcp.csv Format
|
||||
|
||||
The CSV file has the following columns:
|
||||
|
||||
| Column | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| `name` | Yes | Unique server identifier (used in `USE MCP` calls) |
|
||||
| `type` | Yes | Connection type: `stdio`, `http`, `websocket`, `tcp` |
|
||||
| `command` | Yes | For stdio: command to run. For http/ws: URL |
|
||||
| `args` | No | Command arguments (space-separated) or empty |
|
||||
| `description` | No | Human-readable description |
|
||||
| `enabled` | No | `true` or `false` (default: `true`) |
|
||||
| `auth_type` | No | Authentication type: `none`, `api_key`, `bearer` |
|
||||
| `auth_env` | No | Environment variable name for auth credential |
|
||||
| `risk_level` | No | `safe`, `low`, `medium`, `high`, `critical` |
|
||||
| `requires_approval` | No | `true` or `false` (default: `false`) |
|
||||
|
||||
### Example mcp.csv
|
||||
|
||||
```csv
|
||||
name,type,command,args,description,enabled
|
||||
# MCP Server Configuration
|
||||
# Lines starting with # are comments
|
||||
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",Access local files,true
|
||||
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub API,true,bearer,GITHUB_TOKEN
|
||||
postgres,stdio,npx,"-y @modelcontextprotocol/server-postgres",Database queries,false
|
||||
slack,stdio,npx,"-y @modelcontextprotocol/server-slack",Slack messaging,true,bearer,SLACK_BOT_TOKEN
|
||||
myapi,http,https://api.example.com/mcp,,Custom API,true,api_key,MY_API_KEY
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Connection Types
|
||||
|
||||
### stdio (Local Process)
|
||||
|
||||
For MCP servers that run as local processes via npx, node, python, etc:
|
||||
|
||||
```csv
|
||||
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",File access,true
|
||||
```
|
||||
|
||||
The `command` is the executable, and `args` contains the arguments.
|
||||
|
||||
### http (REST API)
|
||||
|
||||
For HTTP-based MCP servers:
|
||||
|
||||
```csv
|
||||
myapi,http,https://api.example.com/mcp,,REST API server,true
|
||||
```
|
||||
|
||||
The `command` is the URL endpoint.
|
||||
|
||||
### websocket
|
||||
|
||||
For WebSocket connections:
|
||||
|
||||
```csv
|
||||
realtime,websocket,wss://ws.example.com/mcp,,Real-time server,true
|
||||
```
|
||||
|
||||
### tcp
|
||||
|
||||
For raw TCP connections:
|
||||
|
||||
```csv
|
||||
legacy,tcp,localhost:9000,,Legacy TCP server,true
|
||||
```
|
||||
|
||||
Format: `host:port` in the command column.
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### API Key
|
||||
|
||||
```csv
|
||||
myapi,http,https://api.example.com,,API Server,true,api_key,MY_API_KEY
|
||||
```
|
||||
|
||||
The environment variable `MY_API_KEY` will be read and sent as `X-API-Key` header.
|
||||
|
||||
### Bearer Token
|
||||
|
||||
```csv
|
||||
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub,true,bearer,GITHUB_TOKEN
|
||||
```
|
||||
|
||||
The environment variable `GITHUB_TOKEN` will be used as a Bearer token.
|
||||
|
||||
> **Security**: Authentication credentials are read from environment variables. Never put actual secrets in mcp.csv.
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Read a File
|
||||
|
||||
```bas
|
||||
' Read a file using filesystem MCP server
|
||||
content = USE MCP "filesystem", "read_file", {"path": "/data/config.json"}
|
||||
TALK "File contents: " + content
|
||||
```
|
||||
|
||||
### Query Database
|
||||
|
||||
```bas
|
||||
' Query PostgreSQL using database MCP server
|
||||
results = USE MCP "postgres", "query", {"sql": "SELECT * FROM users LIMIT 10"}
|
||||
FOR EACH row IN results
|
||||
TALK row.name + " - " + row.email
|
||||
NEXT
|
||||
```
|
||||
|
||||
### Search GitHub
|
||||
|
||||
```bas
|
||||
' Search GitHub repositories
|
||||
repos = USE MCP "github", "search_repositories", {"query": "general bots language:rust"}
|
||||
TALK "Found " + repos.length + " repositories"
|
||||
```
|
||||
|
||||
### Send Slack Message
|
||||
|
||||
```bas
|
||||
' Send message to Slack channel
|
||||
USE MCP "slack", "send_message", {
|
||||
"channel": "#general",
|
||||
"text": "Hello from General Bots!"
|
||||
}
|
||||
```
|
||||
|
||||
### Create GitHub Issue
|
||||
|
||||
```bas
|
||||
' Create an issue (requires approval if configured)
|
||||
issue = USE MCP "github", "create_issue", {
|
||||
"owner": "myorg",
|
||||
"repo": "myproject",
|
||||
"title": "Bug: Login not working",
|
||||
"body": "Users cannot log in with SSO"
|
||||
}
|
||||
TALK "Created issue #" + issue.number
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Keywords
|
||||
|
||||
### MCP LIST TOOLS
|
||||
|
||||
List available tools from an MCP server:
|
||||
|
||||
```bas
|
||||
tools = MCP LIST TOOLS "filesystem"
|
||||
FOR EACH tool IN tools
|
||||
TALK tool.name + ": " + tool.description
|
||||
NEXT
|
||||
```
|
||||
|
||||
### MCP INVOKE
|
||||
|
||||
Alternative syntax for direct tool invocation:
|
||||
|
||||
```bas
|
||||
result = MCP INVOKE "filesystem.read_file", {"path": "/data/file.txt"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Levels
|
||||
|
||||
Tools have risk levels that determine how they're handled:
|
||||
|
||||
| Level | Description | Behavior |
|
||||
|-------|-------------|----------|
|
||||
| **safe** | Read-only, no side effects | Always allowed |
|
||||
| **low** | Minor changes, reversible | Usually allowed |
|
||||
| **medium** | Significant changes | May require approval |
|
||||
| **high** | Destructive or irreversible | Requires approval |
|
||||
| **critical** | System-level changes | Always requires approval |
|
||||
|
||||
When `requires_approval` is set to `true`, the task will pause and wait for human approval before executing the tool.
|
||||
|
||||
---
|
||||
|
||||
## Tool Discovery
|
||||
|
||||
MCP tools are discovered automatically when the server starts. You can see available tools in:
|
||||
|
||||
1. **Sources UI** → MCP Servers tab → View Tools
|
||||
2. **Sources UI** → LLM Tools tab → MCP Tools section
|
||||
3. **BASIC** → `MCP LIST TOOLS "server_name"`
|
||||
|
||||
---
|
||||
|
||||
## Available MCP Servers
|
||||
|
||||
Popular MCP servers you can use:
|
||||
|
||||
| Server | Package | Description |
|
||||
|--------|---------|-------------|
|
||||
| **Filesystem** | `@modelcontextprotocol/server-filesystem` | File operations |
|
||||
| **GitHub** | `@modelcontextprotocol/server-github` | GitHub API |
|
||||
| **PostgreSQL** | `@modelcontextprotocol/server-postgres` | Database queries |
|
||||
| **SQLite** | `@modelcontextprotocol/server-sqlite` | SQLite database |
|
||||
| **Slack** | `@modelcontextprotocol/server-slack` | Slack messaging |
|
||||
| **Puppeteer** | `@modelcontextprotocol/server-puppeteer` | Browser automation |
|
||||
| **Brave Search** | `@modelcontextprotocol/server-brave-search` | Web search |
|
||||
|
||||
See [modelcontextprotocol.io](https://modelcontextprotocol.io) for more servers.
|
||||
|
||||
---
|
||||
|
||||
## Integration with Tasks
|
||||
|
||||
When you add MCP servers to your bot via `mcp.csv`, their tools become available to the Autonomous Task system. The AI can:
|
||||
|
||||
1. **Discover tools** from your MCP servers
|
||||
2. **Plan execution** using MCP tools alongside BASIC keywords
|
||||
3. **Request approval** for high-risk operations
|
||||
4. **Execute tools** and process results
|
||||
|
||||
Example task flow:
|
||||
|
||||
```
|
||||
User: "Read the config file and update the database accordingly"
|
||||
|
||||
AI Plan:
|
||||
1. USE MCP "filesystem", "read_file" → Read config.json
|
||||
2. Parse JSON configuration
|
||||
3. USE MCP "postgres", "query" → Update database
|
||||
4. Report results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Found
|
||||
|
||||
```
|
||||
Error: MCP server 'myserver' not found
|
||||
```
|
||||
|
||||
- Check that `mcp.csv` exists in your `.gbai` folder
|
||||
- Verify the server name matches exactly (case-sensitive)
|
||||
- Ensure `enabled` is not set to `false`
|
||||
- Reload servers in Sources UI
|
||||
|
||||
### Connection Failed
|
||||
|
||||
```
|
||||
Error: Failed to connect to MCP server
|
||||
```
|
||||
|
||||
- Verify the command/URL is correct
|
||||
- Check that required packages are installed (`npm install`)
|
||||
- Ensure environment variables are set for authentication
|
||||
- Test the server manually first
|
||||
|
||||
### Tool Not Available
|
||||
|
||||
```
|
||||
Error: Tool 'unknown_tool' not found on server 'myserver'
|
||||
```
|
||||
|
||||
- List available tools with `MCP LIST TOOLS`
|
||||
- Check tool name spelling
|
||||
- Verify server is properly started
|
||||
|
||||
### Authentication Error
|
||||
|
||||
```
|
||||
Error: Authentication failed for MCP server
|
||||
```
|
||||
|
||||
- Check environment variables are set correctly
|
||||
- Verify credentials are valid
|
||||
- Ensure auth type matches server requirements
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use environment variables** for all credentials
|
||||
2. **Set appropriate risk levels** for tools that modify data
|
||||
3. **Enable approval** for destructive operations
|
||||
4. **Comment your mcp.csv** with `#` lines to document servers
|
||||
5. **Test locally** before deploying
|
||||
6. **Start with enabled=false** for new servers until tested
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Sources](../04-gbui/apps/sources.md) - Managing MCP servers in the UI
|
||||
- [Autonomous Tasks](../07-gbapp/autonomous-tasks.md) - How Tasks use MCP tools
|
||||
- [MCP Format](../09-tools/mcp-format.md) - MCP tool definition format
|
||||
- [LLM Tools](../09-tools/README.md) - All available tool types
|
||||
Loading…
Add table
Reference in a new issue