├── .gitignore ├── glama.json ├── .eslintrc.json ├── .tags.json ├── .semgrepignore ├── .prettierrc.js ├── .github ├── config │ └── .pre-commit-config-template.yaml ├── CODEOWNERS └── workflows │ ├── ci.yml │ ├── vuln-scanner-pr.yml │ ├── secrets-scanner.yml │ └── publish.yml ├── tsconfig.json ├── .yamllint ├── Dockerfile ├── smithery.yaml ├── LICENSE ├── Makefile ├── package.json ├── src └── index.ts └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | build/ 3 | dist/ 4 | *.log 5 | .env* 6 | .npmrc 7 | .DS_Store 8 | -------------------------------------------------------------------------------- /glama.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://glama.ai/mcp/schemas/server.json", 3 | "maintainers": [ 4 | "colriot" 5 | ] 6 | } 7 | -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": [ 3 | "eslint:recommended", 4 | "plugin:@typescript-eslint/recommended", 5 | "prettier" 6 | ] 7 | } 8 | -------------------------------------------------------------------------------- /.tags.json: -------------------------------------------------------------------------------- 1 | { 2 | "repo-owner": "ENG", 3 | "vanta-dependabot-owner": "ENG", 4 | "vanta-ebs-inspector-owner": "ENG", 5 | "vanta-ecr-container-owner": "ENG" 6 | } 7 | -------------------------------------------------------------------------------- /.semgrepignore: -------------------------------------------------------------------------------- 1 | # This file is managed by Terraform in github-control repository 2 | # Do not edit this file, all changes will be overwritten 3 | # If you need to change this file, create a pull request in 4 | # https://github.com/tinyfish-io/github-control 5 | 6 | # Exclude lock files from vulnerability scanning to avoid false positives 7 | **/*.lock 8 | -------------------------------------------------------------------------------- /.prettierrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | printWidth: 120, 3 | trailingComma: 'all', 4 | singleQuote: true, 5 | plugins: ['@trivago/prettier-plugin-sort-imports'], 6 | importOrder: ['', '^@/types/(.*)$', '^@/lib/(.*)$', '^[./]'], 7 | importOrderSeparation: true, 8 | importOrderSortSpecifiers: true, 9 | importOrderCaseInsensitive: false, 10 | }; 11 | -------------------------------------------------------------------------------- /.github/config/.pre-commit-config-template.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | repos: 3 | - repo: "local" 4 | hooks: 5 | - id: "trufflehog" 6 | name: "TruffleHog" 7 | description: Detect secrets in your data. 8 | entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail' 9 | language: system 10 | stages: ["pre-commit", "pre-push"] 11 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2022", 4 | "module": "NodeNext", 5 | "moduleResolution": "NodeNext", 6 | "outDir": "./dist", 7 | "rootDir": "./src", 8 | "strict": true, 9 | "esModuleInterop": true, 10 | "skipLibCheck": true, 11 | "forceConsistentCasingInFileNames": true 12 | }, 13 | "include": ["src/**/*"], 14 | "exclude": ["node_modules"] 15 | } 16 | -------------------------------------------------------------------------------- /.yamllint: -------------------------------------------------------------------------------- 1 | # This file is managed by Terraform in github-control repository 2 | # Do not edit this file, all changes will be overwritten 3 | # If you need to change this file, create a pull request in 4 | # https://github.com/tinyfish-io/github-control 5 | --- 6 | extends: default 7 | 8 | rules: 9 | line-length: 10 | max: 120 11 | level: warning 12 | comments: 13 | min-spaces-from-content: 1 14 | require-starting-space: false 15 | truthy: disable 16 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # This file is managed by Terraform in github-control repository 2 | # Do not edit this file, all changes will be overwritten 3 | # If you need to change this file, create a pull request in 4 | # https://github.com/tinyfish-io/github-control 5 | 6 | .github/workflows/secrets-scanner.yml @tinyfish-io/security_team 7 | .github/workflows/vuln-scanner-pr.yml @tinyfish-io/security_team 8 | .semgrepignore @tinyfish-io/security_team 9 | osv-scanner.toml @tinyfish-io/security_team 10 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM node:20-alpine@sha256:8bda036ddd59ea51a23bc1a1035d3b5c614e72c01366d989f4120e8adca196d4 2 | 3 | WORKDIR /app 4 | 5 | # Copy package files 6 | COPY package*.json ./ 7 | 8 | # Install dependencies 9 | RUN npm install 10 | 11 | # Copy application code 12 | COPY . . 13 | 14 | # Build the application 15 | RUN npm run build 16 | 17 | # Environment variables 18 | ENV AGENTQL_API_KEY=your-api-key 19 | 20 | # Command will be provided by smithery.yaml 21 | CMD ["node", "dist/index.js"] 22 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | pull_request: 7 | branches: [main] 8 | 9 | jobs: 10 | build: 11 | runs-on: ubuntu-latest 12 | 13 | steps: 14 | - name: Checkout Repository 15 | uses: actions/checkout@v4 16 | 17 | - name: Set up Node.js 18 | uses: actions/setup-node@v3 19 | with: 20 | node-version: '20.x' 21 | cache: 'npm' 22 | 23 | - name: Install Dependencies 24 | run: npm ci 25 | 26 | - name: Build 27 | run: npm run build 28 | 29 | - name: Lint 30 | run: npm run lint 31 | -------------------------------------------------------------------------------- /.github/workflows/vuln-scanner-pr.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: OSV-Scanner PR Scan 3 | 4 | on: # yamllint disable-line rule:truthy 5 | pull_request: 6 | branches: [main] 7 | 8 | permissions: 9 | # Required to upload SARIF file to CodeQL. See: https://github.com/github/codeql-action/issues/2117 10 | actions: read 11 | # Require writing security events to upload SARIF file to security tab 12 | security-events: write 13 | # Only need to read contents 14 | contents: read 15 | 16 | jobs: 17 | vulnerability-check: 18 | uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v2.3.1" 19 | with: 20 | scan-args: --config osv-scanner.toml 21 | upload-sarif: false 22 | -------------------------------------------------------------------------------- /smithery.yaml: -------------------------------------------------------------------------------- 1 | # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml 2 | startCommand: 3 | type: stdio 4 | configSchema: 5 | # JSON Schema defining the configuration options for the MCP. 6 | type: object 7 | required: 8 | - agentqlApiKey 9 | properties: 10 | agentqlApiKey: 11 | type: string 12 | description: Your AgentQL API key. You can create one at https://dev.agentql.com. 13 | commandFunction: 14 | # A function that produces the CLI command to start the MCP on stdio. 15 | |- 16 | (config) => ({ 17 | "command": "node", 18 | "args": [ 19 | "dist/index.js" 20 | ], 21 | "env": { 22 | "AGENTQL_API_KEY": config.agentqlApiKey 23 | } 24 | }) 25 | -------------------------------------------------------------------------------- /.github/workflows/secrets-scanner.yml: -------------------------------------------------------------------------------- 1 | # This file is managed by Terraform in github-control repository 2 | # Do not edit this file, all changes will be overwritten 3 | # If you need to change this file, create a pull request in 4 | # https://github.com/tinyfish-io/github-control 5 | --- 6 | name: Leaked Secrets Scan 7 | on: # yamllint disable-line rule:truthy 8 | pull_request: 9 | merge_group: 10 | branches: [main] 11 | 12 | jobs: 13 | TruffleHog: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Checkout code 17 | uses: actions/checkout@v4 18 | with: 19 | fetch-depth: 0 20 | - name: TruffleHog OSS 21 | uses: trufflesecurity/trufflehog@main 22 | with: 23 | path: ./ 24 | base: ${{ github.event.repository.default_branch }} 25 | head: HEAD 26 | extra_args: --only-verified 27 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Tiny Fish 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | SHELL := /usr/bin/env bash 2 | 3 | include $(wildcard makefiles/*) 4 | 5 | .PHONY: check-trufflehog 6 | check-trufflehog: 7 | @if ! which trufflehog > /dev/null 2>&1; then \ 8 | echo "TruffleHog is not installed."; \ 9 | echo "MacOS users can install it with:"; \ 10 | echo " brew install trufflehog"; \ 11 | echo ""; \ 12 | echo "Linux users can install it with:"; \ 13 | echo " curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin"; \ 14 | echo ""; \ 15 | echo "For more details, go to https://github.com/trufflesecurity/trufflehog"; \ 16 | exit 1; \ 17 | fi 18 | 19 | .PHONY: setup-pre-commit 20 | setup-pre-commit: 21 | @if [ ! -f .pre-commit-config.yaml ]; then \ 22 | echo ".pre-commit-config.yaml not found. Copying template..."; \ 23 | cp .github/config/.pre-commit-config-template.yaml .pre-commit-config.yaml; \ 24 | echo ".pre-commit-config.yaml created from template."; \ 25 | else \ 26 | echo ".pre-commit-config.yaml already exists."; \ 27 | fi 28 | 29 | .PHONY: init 30 | init: setup-pre-commit check-trufflehog 31 | pip install pre-commit 32 | pre-commit install 33 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "agentql-mcp", 3 | "version": "1.0.0", 4 | "description": "Model Context Protocol (MCP) server that integrates AgentQL data extraction capabilities.", 5 | "license": "MIT", 6 | "repository": "https://github.com/tinyfish-io/agentql-mcp.git", 7 | "type": "module", 8 | "bin": { 9 | "agentql-mcp": "./dist/index.js" 10 | }, 11 | "files": [ 12 | "dist" 13 | ], 14 | "scripts": { 15 | "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"", 16 | "prepare": "npm run build", 17 | "watch": "tsc --watch", 18 | "inspector": "npx @modelcontextprotocol/inspector dist/index.js", 19 | "lint": "eslint src", 20 | "lint:fix": "npm run lint -- --fix", 21 | "format": "prettier --write src" 22 | }, 23 | "dependencies": { 24 | "@modelcontextprotocol/sdk": "1.6.1", 25 | "node-fetch": "^3.3.2" 26 | }, 27 | "devDependencies": { 28 | "@trivago/prettier-plugin-sort-imports": "^4.3.0", 29 | "@types/node": "^20.11.24", 30 | "@types/node-fetch": "^2.6.12", 31 | "@typescript-eslint/eslint-plugin": "^8.4.0", 32 | "eslint": "^8.57.0", 33 | "eslint-config-prettier": "^9.1.0", 34 | "prettier": "^3.4.2", 35 | "typescript": "^5.3.3" 36 | }, 37 | "keywords": [ 38 | "mcp", 39 | "agentql", 40 | "data-extraction", 41 | "web-scraping", 42 | "content-extraction" 43 | ] 44 | } 45 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish Package 2 | 3 | on: 4 | release: 5 | types: [created] 6 | workflow_dispatch: 7 | 8 | jobs: 9 | publish: 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - name: Checkout Repository 14 | uses: actions/checkout@v4 15 | 16 | - name: Set up Node.js 17 | uses: actions/setup-node@v4 18 | with: 19 | node-version: '20.x' 20 | cache: 'npm' 21 | registry-url: 'https://registry.npmjs.org' 22 | 23 | - name: Install Dependencies 24 | run: npm ci 25 | 26 | - name: Check if Version Was Bumped 27 | run: | 28 | published=$(npm view agentql-mcp version || echo "0.0.0") 29 | current=$(node -p "require('./package.json').version") 30 | echo "Published version: $published" 31 | echo "Current version: $current" 32 | if [ "$published" != "$current" ]; then 33 | echo "PUBLISH=yes" >> $GITHUB_ENV 34 | else 35 | echo "PUBLISH=no" >> $GITHUB_ENV 36 | echo "Version $current already exists on NPM" 37 | fi 38 | 39 | - name: Build 40 | if: ${{ env.PUBLISH == 'yes' }} 41 | run: npm run build 42 | 43 | - name: Publish to NPM 44 | if: ${{ env.PUBLISH == 'yes' }} 45 | run: npm publish 46 | env: 47 | NODE_AUTH_TOKEN: ${{ secrets.NPM_API_TOKEN }} 48 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | import { Server } from '@modelcontextprotocol/sdk/server/index.js'; 3 | import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; 4 | import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; 5 | import fetch from 'node-fetch'; 6 | 7 | // Interface for parsing AQL REST API response. 8 | interface AqlResponse { 9 | data: object; 10 | } 11 | 12 | // Create an MCP server with only tools capability (trigger 'query-data' call). 13 | const server = new Server( 14 | { 15 | name: 'agentql-mcp', 16 | version: '1.0.0', 17 | }, 18 | { 19 | capabilities: { 20 | tools: {}, 21 | }, 22 | }, 23 | ); 24 | 25 | const EXTRACT_TOOL_NAME = 'extract-web-data'; 26 | const AGENTQL_API_KEY = process.env.AGENTQL_API_KEY; 27 | 28 | if (!AGENTQL_API_KEY) { 29 | console.error('Error: AGENTQL_API_KEY environment variable is required'); 30 | process.exit(1); 31 | } 32 | 33 | // Handler that lists available tools. 34 | server.setRequestHandler(ListToolsRequestSchema, async () => { 35 | return { 36 | tools: [ 37 | { 38 | name: EXTRACT_TOOL_NAME, 39 | description: 40 | 'Extracts structured data as JSON from a web page given a URL using a Natural Language description of the data.', 41 | inputSchema: { 42 | type: 'object', 43 | properties: { 44 | url: { 45 | type: 'string', 46 | description: 'The URL of the public webpage to extract data from', 47 | }, 48 | prompt: { 49 | type: 'string', 50 | description: 'Natural Language description of the data to extract from the page', 51 | }, 52 | }, 53 | required: ['url', 'prompt'], 54 | }, 55 | }, 56 | ], 57 | }; 58 | }); 59 | 60 | // Handler for the 'extract-web-data' tool. 61 | server.setRequestHandler(CallToolRequestSchema, async (request) => { 62 | switch (request.params.name) { 63 | case EXTRACT_TOOL_NAME: { 64 | const url = String(request.params.arguments?.url); 65 | const prompt = String(request.params.arguments?.prompt); 66 | if (!url || !prompt) { 67 | throw new Error("Both 'url' and 'prompt' are required"); 68 | } 69 | 70 | const endpoint = 'https://api.agentql.com/v1/query-data'; 71 | const response = await fetch(endpoint, { 72 | method: 'POST', 73 | headers: { 74 | 'X-API-Key': `${AGENTQL_API_KEY}`, 75 | 'X-TF-Request-Origin': 'mcp-server', 76 | 'Content-Type': 'application/json', 77 | }, 78 | body: JSON.stringify({ 79 | url: url, 80 | prompt: prompt, 81 | params: { 82 | wait_for: 0, 83 | is_scroll_to_bottom_enabled: false, 84 | mode: 'fast', 85 | is_screenshot_enabled: false, 86 | }, 87 | }), 88 | }); 89 | 90 | if (!response.ok) { 91 | throw new Error(`AgentQL API error: ${response.statusText}\n${await response.text()}`); 92 | } 93 | 94 | const json = (await response.json()) as AqlResponse; 95 | 96 | return { 97 | content: [ 98 | { 99 | type: 'text', 100 | text: JSON.stringify(json.data, null, 2), 101 | }, 102 | ], 103 | }; 104 | } 105 | 106 | default: 107 | throw new Error(`Unknown tool: '${request.params.name}'`); 108 | } 109 | }); 110 | 111 | // Start the server using stdio transport. 112 | async function main() { 113 | const transport = new StdioServerTransport(); 114 | await server.connect(transport); 115 | } 116 | 117 | main().catch((error) => { 118 | console.error('Server error:', error); 119 | process.exit(1); 120 | }); 121 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # AgentQL MCP Server 2 | 3 | This is a Model Context Protocol (MCP) server that integrates [AgentQL](https://agentql.com)'s data extraction capabilities. 4 | 5 | ## Features 6 | 7 | ### Tools 8 | 9 | - `extract-web-data` - extract structured data from a given 'url', using 'prompt' as a description of actual data and its fields to extract. 10 | 11 | ## Installation 12 | 13 | To use AgentQL MCP Server to extract data from web pages, you need to install it via npm, get an API key from our [Dev Portal](https://dev.agentql.com), and configure it in your favorite app that supports MCP. 14 | 15 | ### Install the package 16 | 17 | ```bash 18 | npm install -g agentql-mcp 19 | ``` 20 | 21 | ### Configure Claude 22 | 23 | - Open Claude Desktop **Settings** via `⌘`+`,` (don't confuse with Claude Account Settings) 24 | - Go to **Developer** sidebar section 25 | - Click **Edit Config** and open `claude_desktop_config.json` file 26 | - Add `agentql` server inside `mcpServers` dictionary in the config file 27 | - Restart the app 28 | 29 | ```json title="claude_desktop_config.json" 30 | { 31 | "mcpServers": { 32 | "agentql": { 33 | "command": "npx", 34 | "args": ["-y", "agentql-mcp"], 35 | "env": { 36 | "AGENTQL_API_KEY": "YOUR_API_KEY" 37 | } 38 | } 39 | } 40 | } 41 | ``` 42 | 43 | Read more about MCP configuration in Claude [here](https://modelcontextprotocol.io/quickstart/user). 44 | 45 | ### Configure VS Code 46 | 47 | For one-click installation, click one of the install buttons below: 48 | 49 | [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=agentql&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22agentql-mcp%22%5D%2C%22env%22%3A%7B%22AGENTQL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22AgentQL+API+Key%22%2C%22password%22%3Atrue%7D%5D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=agentql&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22agentql-mcp%22%5D%2C%22env%22%3A%7B%22AGENTQL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22AgentQL+API+Key%22%2C%22password%22%3Atrue%7D%5D&quality=insiders) 50 | 51 | #### Manual Installation 52 | 53 | Click the install buttons at the top of this section for the quickest installation method. For manual installation, follow these steps: 54 | 55 | Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`. 56 | 57 | ```json 58 | { 59 | "mcp": { 60 | "inputs": [ 61 | { 62 | "type": "promptString", 63 | "id": "apiKey", 64 | "description": "AgentQL API Key", 65 | "password": true 66 | } 67 | ], 68 | "servers": { 69 | "agentql": { 70 | "command": "npx", 71 | "args": ["-y", "agentql-mcp"], 72 | "env": { 73 | "AGENTQL_API_KEY": "${input:apiKey}" 74 | } 75 | } 76 | } 77 | } 78 | } 79 | ``` 80 | 81 | Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others. 82 | 83 | ```json 84 | { 85 | "inputs": [ 86 | { 87 | "type": "promptString", 88 | "id": "apiKey", 89 | "description": "AgentQL API Key", 90 | "password": true 91 | } 92 | ], 93 | "servers": { 94 | "agentql": { 95 | "command": "npx", 96 | "args": ["-y", "agentql-mcp"], 97 | "env": { 98 | "AGENTQL_API_KEY": "${input:apiKey}" 99 | } 100 | } 101 | } 102 | } 103 | ``` 104 | 105 | ### Configure Cursor 106 | 107 | - Open **Cursor Settings** 108 | - Go to **MCP > MCP Servers** 109 | - Click **+ Add new MCP Server** 110 | - Enter the following: 111 | - Name: "agentql" (or your preferred name) 112 | - Type: "command" 113 | - Command: `env AGENTQL_API_KEY=YOUR_API_KEY npx -y agentql-mcp` 114 | 115 | Read more about MCP configuration in Cursor [here](https://docs.cursor.com/context/model-context-protocol). 116 | 117 | ### Configure Windsurf 118 | 119 | - Open **Windsurf: MCP Configuration Panel** 120 | - Click **Add custom server+** 121 | - Alternatively you can open `~/.codeium/windsurf/mcp_config.json` directly 122 | - Add `agentql` server inside `mcpServers` dictionary in the config file 123 | 124 | ```json title="mcp_config.json" 125 | { 126 | "mcpServers": { 127 | "agentql": { 128 | "command": "npx", 129 | "args": ["-y", "agentql-mcp"], 130 | "env": { 131 | "AGENTQL_API_KEY": "YOUR_API_KEY" 132 | } 133 | } 134 | } 135 | } 136 | ``` 137 | 138 | Read more about MCP configuration in Windsurf [here](https://docs.codeium.com/windsurf/mcp). 139 | 140 | ### Validate MCP integration 141 | 142 | Give your agent a task that will require extracting data from the web. For example: 143 | 144 | ```text 145 | Extract the list of videos from the page https://www.youtube.com/results?search_query=agentql, every video should have a title, an author name, a number of views and a url to the video. Make sure to exclude ads items. Format this as a markdown table. 146 | ``` 147 | 148 | > [!TIP] 149 | > In case your agent complains that it can't open urls or load content from the web instead of using AgentQL, try adding "use tools" or "use agentql tool" hint. 150 | 151 | ## Development 152 | 153 | Install dependencies: 154 | 155 | ```bash 156 | npm install 157 | ``` 158 | 159 | Build the server: 160 | 161 | ```bash 162 | npm run build 163 | ``` 164 | 165 | For development with auto-rebuild: 166 | 167 | ```bash 168 | npm run watch 169 | ``` 170 | 171 | If you want to try out development version, you can use the following config instead of the default one: 172 | 173 | ```json 174 | { 175 | "mcpServers": { 176 | "agentql": { 177 | "command": "/path/to/agentql-mcp/dist/index.js", 178 | "env": { 179 | "AGENTQL_API_KEY": "YOUR_API_KEY" 180 | } 181 | } 182 | } 183 | } 184 | ``` 185 | 186 | > [!NOTE] 187 | > Don't forget to remove the default AgentQL MCP server config to not confuse Claude with two similar servers. 188 | 189 | ## Debugging 190 | 191 | Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script: 192 | 193 | ```bash 194 | npm run inspector 195 | ``` 196 | 197 | The Inspector will provide a URL to access debugging tools in your browser. 198 | --------------------------------------------------------------------------------