From 117a900fbf30502227548054bf94b2f07d237280 Mon Sep 17 00:00:00 2001 From: RohanDisa <105740583+RohanDisa@users.noreply.github.com> Date: Thu, 25 Sep 2025 22:57:20 -0700 Subject: [PATCH] Add complete VSCode integration documentation --- modelcontextprotocol/README.md | 108 ++++++++- modelcontextprotocol/docs/DEPLOYMENT.md | 33 ++- .../docs/VSCODE_INTEGRATION.md | 229 ++++++++++++++++++ 3 files changed, 368 insertions(+), 2 deletions(-) create mode 100644 modelcontextprotocol/docs/VSCODE_INTEGRATION.md diff --git a/modelcontextprotocol/README.md b/modelcontextprotocol/README.md index 6c55320..cb5fd8b 100644 --- a/modelcontextprotocol/README.md +++ b/modelcontextprotocol/README.md @@ -135,6 +135,110 @@ Open `Cursor > Settings > Tools & Integrations > New MCP Server` to include the } ``` +### Add to VSCode + +VSCode integration with MCP servers is evolving. Here are the current approaches: + +#### Option 1: AI Toolkit Extension (Recommended) + +1. **Install the AI Toolkit Extension:** + - Open VSCode Extensions (`Ctrl+Shift+X`) + - Search for "AI Toolkit" by Microsoft + - Install the extension + +2. **Configure MCP Server:** + - Open Command Palette (`Ctrl+Shift+P`) + - Run "AI Toolkit: Open Agent Builder" + - In the Agent Builder, click "+ MCP Server" + - Choose "Command (stdio)" connection type + - Configure with the following settings: + ``` + Command: uvx + Arguments: atlan-mcp-server + Environment Variables: + ATLAN_API_KEY: + ATLAN_BASE_URL: https://.atlan.com + ATLAN_AGENT_ID: + ``` + +3. **Test the Integration:** + - Use the Agent Builder to create prompts that utilize Atlan tools + - Test asset search, lineage traversal, and other Atlan operations + +#### Option 2: Manual Configuration (Advanced) + +If you prefer manual configuration or need more control: + +1. **Create VSCode Settings:** + - Open VSCode Settings (`Ctrl+,`) + - Search for "mcp" or "model context protocol" + - Add configuration in your `settings.json`: + +```json +{ + "mcp.servers": { + "atlan": { + "command": "uvx", + "args": ["atlan-mcp-server"], + "env": { + "ATLAN_API_KEY": "", + "ATLAN_BASE_URL": "https://.atlan.com", + "ATLAN_AGENT_ID": "" + } + } + } +} +``` + +2. **Install MCP Extension:** + - Search for "MCP" or "Model Context Protocol" in VSCode Extensions + - Install any available MCP-related extensions + +#### Option 3: Development Mode + +For development and testing: + +1. **Clone and Setup:** + ```bash + git clone https://github.com/atlanhq/agent-toolkit.git + cd agent-toolkit/modelcontextprotocol + uv sync + ``` + +2. **Create .env file:** + ```env + ATLAN_BASE_URL=https://your-instance.atlan.com + ATLAN_API_KEY=your_api_key + ATLAN_AGENT_ID=your_agent_id + ``` + +3. **Run in Development Mode:** + ```bash + uv run mcp dev server.py + ``` + +4. **Configure VSCode for Local Development:** + - Use the local path in your MCP configuration: + ```json + { + "mcp.servers": { + "atlan-local": { + "command": "uv", + "args": ["run", "/path/to/agent-toolkit/modelcontextprotocol/.venv/bin/atlan-mcp-server"], + "cwd": "/path/to/agent-toolkit/modelcontextprotocol", + "env": { + "ATLAN_API_KEY": "", + "ATLAN_BASE_URL": "https://.atlan.com", + "ATLAN_AGENT_ID": "" + } + } + } + } + ``` + +> [!NOTE] +> VSCode MCP integration is still evolving. The AI Toolkit extension is the most mature option currently available. For the latest updates on VSCode MCP support, check the [Model Context Protocol documentation](https://modelcontextprotocol.io/). + ## Available Tools | Tool | Description | @@ -250,12 +354,14 @@ The Atlan MCP Server supports three transport modes, each optimized for differen | Transport Mode | Use Case | Benefits | When to Use | |---|---|---|---| -| **stdio** (Default) | Local development, IDE integrations | Simple, direct communication | Claude Desktop, Cursor IDE | +| **stdio** (Default) | Local development, IDE integrations | Simple, direct communication | Claude Desktop, Cursor IDE, VSCode | | **SSE** (Server-Sent Events) | Remote deployments, web browsers | Real-time streaming, web-compatible | Cloud deployments, web clients | | **streamable-http** | HTTP-based remote connections | Standard HTTP, load balancer friendly | Kubernetes, containerized deployments | For comprehensive deployment instructions, configuration examples, and production best practices, see our [Deployment Guide](./docs/Deployment.md). +For detailed VSCode integration instructions, see our [VSCode Integration Guide](./docs/VSCODE_INTEGRATION.md). + ## Production Deployment - Host the Atlan MCP container image on the cloud/platform of your choice diff --git a/modelcontextprotocol/docs/DEPLOYMENT.md b/modelcontextprotocol/docs/DEPLOYMENT.md index 4969b8e..e6c4e6f 100644 --- a/modelcontextprotocol/docs/DEPLOYMENT.md +++ b/modelcontextprotocol/docs/DEPLOYMENT.md @@ -8,7 +8,7 @@ The Atlan MCP Server supports three transport modes. For more details about MCP | Transport Mode | Use Case | Benefits | When to Use | |---|---|---|---| -| **stdio** (Default) | Local development, IDE integrations | Simple, direct communication | Claude Desktop, Cursor IDE | +| **stdio** (Default) | Local development, IDE integrations | Simple, direct communication | Claude Desktop, Cursor IDE, VSCode | | **SSE** (Server-Sent Events) | Remote deployments, web browsers | Real-time streaming, web-compatible | Cloud deployments, web clients | | **streamable-http** | HTTP-based remote connections | Standard HTTP, load balancer friendly | Kubernetes, containerized deployments | @@ -23,6 +23,37 @@ python server.py python server.py --transport stdio ``` +### VSCode Integration + +VSCode integration with MCP servers supports multiple approaches: + +#### Using AI Toolkit Extension +```bash +# Install the AI Toolkit extension in VSCode +# Then configure MCP server through the Agent Builder interface +# Command: uvx +# Arguments: atlan-mcp-server +# Environment Variables: ATLAN_API_KEY, ATLAN_BASE_URL, ATLAN_AGENT_ID +``` + +#### Manual VSCode Configuration +```json +// In VSCode settings.json +{ + "mcp.servers": { + "atlan": { + "command": "uvx", + "args": ["atlan-mcp-server"], + "env": { + "ATLAN_API_KEY": "", + "ATLAN_BASE_URL": "https://.atlan.com", + "ATLAN_AGENT_ID": "" + } + } + } +} +``` + ### Cloud Deployment (SSE) ```bash # Docker with SSE diff --git a/modelcontextprotocol/docs/VSCODE_INTEGRATION.md b/modelcontextprotocol/docs/VSCODE_INTEGRATION.md new file mode 100644 index 0000000..1a3bf6f --- /dev/null +++ b/modelcontextprotocol/docs/VSCODE_INTEGRATION.md @@ -0,0 +1,229 @@ +# VSCode Integration Guide + +This guide provides comprehensive instructions for integrating the Atlan MCP Server with Visual Studio Code (VSCode). + +## Prerequisites + +- Visual Studio Code installed +- Python 3.11+ (if using local development) +- Atlan API credentials (API key and instance URL) + +## Integration Methods + +### Method 1: AI Toolkit Extension (Recommended) + +The Microsoft AI Toolkit extension provides the most mature MCP integration for VSCode. + +#### Installation Steps + +1. **Install AI Toolkit Extension:** + - Open VSCode + - Go to Extensions (`Ctrl+Shift+X` or `Cmd+Shift+X`) + - Search for "AI Toolkit" by Microsoft + - Click "Install" + +2. **Open Agent Builder:** + - Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) + - Type "AI Toolkit: Open Agent Builder" + - Select the command + +3. **Configure MCP Server:** + - In the Agent Builder interface, click "+ MCP Server" + - Choose "Command (stdio)" as the connection type + - Fill in the configuration: + ``` + Command: uvx + Arguments: atlan-mcp-server + Environment Variables: + ATLAN_API_KEY: your_api_key_here + ATLAN_BASE_URL: https://your-instance.atlan.com + ATLAN_AGENT_ID: your_agent_id_here (optional) + ``` + +4. **Test the Integration:** + - Create a new agent in the Agent Builder + - Add prompts that utilize Atlan tools + - Test asset search, lineage traversal, and other operations + +#### Example Agent Prompts + +``` +Search for all verified tables in the database: +- Use the search_assets_tool with asset_type="Table" and certificate_status="VERIFIED" + +Find the lineage for a specific asset: +- Use the traverse_lineage_tool with the asset's GUID and direction="DOWNSTREAM" + +Update asset descriptions: +- Use the update_assets_tool to add user descriptions to multiple assets +``` + +### Method 2: Manual Configuration + +For advanced users who need more control over the configuration. + +#### Step 1: Install MCP Extension + +1. Search for "MCP" or "Model Context Protocol" in VSCode Extensions +2. Install any available MCP-related extensions + +#### Step 2: Configure Settings + +1. Open VSCode Settings (`Ctrl+,` or `Cmd+,`) +2. Click "Open Settings (JSON)" in the top right +3. Add the following configuration: + +```json +{ + "mcp.servers": { + "atlan": { + "command": "uvx", + "args": ["atlan-mcp-server"], + "env": { + "ATLAN_API_KEY": "your_api_key_here", + "ATLAN_BASE_URL": "https://your-instance.atlan.com", + "ATLAN_AGENT_ID": "your_agent_id_here" + } + } + } +} +``` + +#### Step 3: Restart VSCode + +Restart VSCode to ensure the configuration is loaded. + +### Method 3: Local Development Setup + +For developers who want to modify or extend the MCP server. + +#### Step 1: Clone and Setup + +```bash +git clone https://github.com/atlanhq/agent-toolkit.git +cd agent-toolkit/modelcontextprotocol +uv sync +``` + +#### Step 2: Create Environment File + +Create a `.env` file in the `modelcontextprotocol` directory: + +```env +ATLAN_BASE_URL=https://your-instance.atlan.com +ATLAN_API_KEY=your_api_key_here +ATLAN_AGENT_ID=your_agent_id_here +``` + +#### Step 3: Configure VSCode for Local Development + +Update your VSCode settings to use the local installation: + +```json +{ + "mcp.servers": { + "atlan-local": { + "command": "uv", + "args": ["run", "/absolute/path/to/agent-toolkit/modelcontextprotocol/.venv/bin/atlan-mcp-server"], + "cwd": "/absolute/path/to/agent-toolkit/modelcontextprotocol", + "env": { + "ATLAN_API_KEY": "your_api_key_here", + "ATLAN_BASE_URL": "https://your-instance.atlan.com", + "ATLAN_AGENT_ID": "your_agent_id_here" + } + } + } +} +``` + +#### Step 4: Development Mode + +For debugging and development: + +```bash +# Run with MCP inspector +uv run mcp dev server.py + +# Or run normally +uv run .venv/bin/atlan-mcp-server +``` + +## Available Tools in VSCode + +Once integrated, you'll have access to these Atlan tools: + +| Tool | Description | Use Case | +|------|-------------|----------| +| `search_assets_tool` | Search for assets with flexible conditions | Find tables, columns, or other assets | +| `get_assets_by_dsl_tool` | Execute complex DSL queries | Advanced search scenarios | +| `traverse_lineage_tool` | Navigate asset lineage | Understand data flow and dependencies | +| `update_assets_tool` | Update asset attributes | Add descriptions, change certificates | +| `query_asset_tool` | Execute SQL on table/view assets | Query data directly from sources | +| `create_glossaries` | Create new glossaries | Set up data governance structures | +| `create_glossary_categories` | Create glossary categories | Organize terms hierarchically | +| `create_glossary_terms` | Create glossary terms | Define business terminology | + +## Troubleshooting + +### Common Issues + +1. **Extension Not Found:** + - Ensure you're using the correct extension name + - Check if the extension is compatible with your VSCode version + +2. **MCP Server Not Starting:** + - Verify your API credentials are correct + - Check that `uvx` is installed and in your PATH + - Review the VSCode output panel for error messages + +3. **Tools Not Available:** + - Restart VSCode after configuration changes + - Check that the MCP server is running without errors + - Verify environment variables are set correctly + +### Debug Mode + +Enable debug logging by adding to your VSCode settings: + +```json +{ + "mcp.debug": true, + "mcp.logLevel": "debug" +} +``` + +### Getting Help + +- Check the [Model Context Protocol documentation](https://modelcontextprotocol.io/) +- Review the [Atlan MCP Server README](../README.md) +- Open an issue on the [GitHub repository](https://github.com/atlanhq/agent-toolkit/issues) + +## Best Practices + +1. **Use Environment Variables:** Store sensitive credentials in environment variables rather than hardcoding them +2. **Test Incrementally:** Start with simple operations before moving to complex workflows +3. **Monitor Performance:** Be aware of API rate limits and query performance +4. **Version Control:** Keep your VSCode settings in version control for team consistency + +## Example Workflows + +### Data Discovery Workflow + +1. Search for assets by type and certification status +2. Examine asset lineage to understand data flow +3. Query sample data to understand content +4. Update asset descriptions based on findings + +### Governance Setup Workflow + +1. Create glossaries for different business domains +2. Set up category hierarchies within glossaries +3. Create terms and associate them with categories +4. Link terms to relevant assets + +### Data Quality Workflow + +1. Find assets missing descriptions +2. Identify uncertified but frequently used assets +3. Update asset metadata to improve governance +4. Create glossary terms for standardized definitions