背景连接器

一个基于上下文引擎SDK的开源库,使得不同的源可以跨代理和应用程序搜索.

特征

• 多来源: 来自 GitHub 、 GitLab 、 BitBucket 或网站的索引代码、文档、 运行本、 策略和配置
• 弹性存储: 在当地或S3中存储索引,用于在生产应用程序中持续存储
• 多个客户端: CLI 搜索, 交互式代理, MCP 服务器( 本地和远程)
• 递增更新: 只重新索引已改变的东西
• 智能过滤: 尊重 .gitignore, (中文(简体) ), .augmentignore,并过滤二进制/生成的文件

安装

npm install @augmentcode/context-connectors

基于您的使用大小写安装可选依赖 :

# For GitHub source
npm install @octokit/rest

# For S3 storage
npm install @aws-sdk/client-s3

# For MCP server (Claude Desktop)
npm install @modelcontextprotocol/sdk

快速启动

1. 索引代码库

# Set required environment variables
export AUGMENT_API_TOKEN='your-token'
export AUGMENT_API_URL='https://your-tenant.api.augmentcode.com/'

# Index a GitHub repository
export GITHUB_TOKEN='your-github-token'
npx context-connectors index github --owner myorg --repo myrepo -i my-project

# Index a BitBucket repository
export BITBUCKET_TOKEN='your-bitbucket-token'
npx context-connectors index bitbucket --workspace myworkspace --repo myrepo -i my-project

# Index a website
npx context-connectors index website --url https://docs.example.com -i my-docs

2. 搜索

# Search and get an AI-generated answer (default)
npx context-connectors search "authentication logic" -i my-project

# Get raw search results without AI processing
npx context-connectors search "API routes" -i my-project --raw

3. 互动代理

npx context-connectors agent -i my-project --provider openai

CLI 命令

index - 数据来源索引

context-connectors index <source> [options]

所有来源的共同备选方案:

GitHub 特定选项

GitLab 特定选项

BitBucket 特定选项

特定网站选项

search - 搜索索引内容

context-connectors search <query> [options]

agent - 交互式人工智能代理

context-connectors agent [query] [options]

提供者默认模式 :

• openai数字 : gpt-5-mini
• anthropic数字 : claude-haiku-4-5
• google数字 : gemini-3-flash-preview

list - 列出本地索引

context-connectors list [options]

delete - 删除本地索引

context-connectors delete <name> [options]

mcp stdio - 启动使用 stdio 传输的 MCP 服务器

context-connectors mcp stdio [options]

mcp http - 启动使用 HTTP 传输的 MCP 服务器

为远程客户端启动一个可以通过HTTP访问的MCP服务器.

context-connectors mcp http [options]

示例

# Start server on port 8080, allow any CORS origin
context-connectors mcp http -i my-project --port 8080 --cors "*"

# With authentication
context-connectors mcp http -i my-project --api-key "secret-key"

# Or use environment variable for the key
MCP_API_KEY="secret-key" context-connectors mcp http -i my-project

关于 --search-only

默认情况下,所有命令都提供 list_files 财务报告和审定财务报表 read_file 工具,除 search启用 --search-only 并仅提供 search 工具.

程序用途

基本索引编制

import { Indexer } from "@augmentcode/context-connectors";
import { GitHubSource } from "@augmentcode/context-connectors/sources";
import { FilesystemStore } from "@augmentcode/context-connectors/stores";

const source = new GitHubSource({ owner: "myorg", repo: "myrepo" });
const store = new FilesystemStore({ basePath: ".context-connectors" });
const indexer = new Indexer();

const result = await indexer.index(source, store, "my-project");
console.log(`Indexed ${result.filesIndexed} files`);

搜索客户端

import { SearchClient } from "@augmentcode/context-connectors";
import { FilesystemStore } from "@augmentcode/context-connectors/stores";

const store = new FilesystemStore({ basePath: ".context-connectors" });
const client = new SearchClient({ store, indexName: "my-project" });
await client.initialize(); // Required before calling search()

const result = await client.search("authentication");
console.log(result.results);

重要内容: 你必须打电话 await client.initialize() 打电话前 search()。这可以加载索引状态,并为客户端的查询做好准备。 通话 search() 或者说 getMetadata() 在初始化之前,会丢出“ Client not irginized” 错误.

MCP 服务器

import { runMCPServer } from "@augmentcode/context-connectors";
import { FilesystemStore } from "@augmentcode/context-connectors/stores";

const store = new FilesystemStore({ basePath: ".context-connectors" });

await runMCPServer({
  store,
  indexName: "my-project",
});

MCP HTTP 服务器

import { runMCPHttpServer } from "@augmentcode/context-connectors";
import { FilesystemStore } from "@augmentcode/context-connectors/stores";

const store = new FilesystemStore({ basePath: ".context-connectors" });

const server = await runMCPHttpServer({
  store,
  indexName: "my-project",
  port: 3000,
  host: "0.0.0.0",
  cors: "*",
  apiKey: process.env.MCP_API_KEY,
});

console.log(`MCP server running at ${server.getUrl()}`);

// Graceful shutdown
process.on("SIGTERM", () => server.stop());

安全考虑

MCP HTTP 服务器安全

远程 MCP 服务器使用 没有 TLS 的 HTTP 默认。 这对安全有重要影响:

⚠️ API 密钥和所有数据以清晰文本传输 当使用普通 HTTP 时。 这意味着任何能够观测网络流量(通过MITM攻击,网络嗅觉等)的人都可以捕捉到资质和数据.

建议部署

促进发展(仅当地主办)

约束时 localhost (默认),交通 永远不会离开你的机器:

# Safe: localhost only (default)
context-connectors mcp http -i my-project --api-key "$MCP_API_KEY"

用于生产:使用 TLS- 终结倒置代理

将 MCP 服务器置于处理 TLS 的倒置代理服务器后. 以下是凯迪的例子( 自动获得证书):

# Caddyfile
mcp.yourdomain.com {
    reverse_proxy localhost:3000
}

然后在本地主机上运行 MCP 服务器 :

context-connectors mcp http -i my-project --api-key "$MCP_API_KEY" --port 3000

替代品: nginx 带有加密

server {
    listen 443 ssl;
    server_name mcp.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;
    
    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # For SSE streaming
        proxy_buffering off;
        proxy_cache off;
    }
}

替代品:SSH 隧道

对于临时hoc远程访问,请使用SSH端口转发:

# On the server
context-connectors mcp http -i my-project --api-key "$MCP_API_KEY"

# On your local machine
ssh -L 3000:localhost:3000 user@server

# Now connect to localhost:3000 on your local machine

网络隔离

如果 TLS 不可行, 请确保服务器在 :

• 一个没有公共互联网接入的私营VPC/网络
• 一个有防火墙限制访问的可信任的网络段
• 带有网络策略的 Docker 网络或 Kubernetes 集群

认证

总是使用 API 密钥进行任何非本地主机部署 :

# Set via environment variable (recommended - avoids key in shell history)
export MCP_API_KEY="your-secure-random-key"
context-connectors mcp http -i my-project

# Or via command line option
context-connectors mcp http -i my-project --api-key "your-secure-random-key"

生成一个安全密钥 :

openssl rand -base64 32

克劳德桌面集成

添加到您的 Claude 桌面配置( E)~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-project": {
      "command": "npx",
      "args": ["context-connectors", "mcp", "stdio", "-i", "my-project"],
      "env": {
        "AUGMENT_API_TOKEN": "your-token",
        "AUGMENT_API_URL": "https://your-tenant.api.augmentcode.com/"
      }
    }
  }
}

远程 MCP 客户端集成

这个 mcp http 命令使用 MCP 流式 HTTP 传输方式,在 HTTP 上显示您的索引数据。 任何MCP相容客户端都可以连接.

正在连接 MCP SDK

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp"),
  {
    requestInit: {
      headers: {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
);

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call search tool
const result = await client.callTool("search", { query: "authentication" });
console.log(result);

用卷轴测试

# List tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call search tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"authentication"}}}'

GitHub 动作

每次按下自动索引 :

name: Index Repository

on:
  push:
    branches: [main]

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Index repository
        run: |
          npx @augmentcode/context-connectors index github \
            --owner ${{ github.repository_owner }} \
            --repo ${{ github.event.repository.name }} \
            --ref ${{ github.sha }} \
            -i ${{ github.ref_name }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AUGMENT_API_TOKEN: ${{ secrets.AUGMENT_API_TOKEN }}
          AUGMENT_API_URL: ${{ secrets.AUGMENT_API_URL }}

GitHub Webhook 集成

使用 GitHub webhooks 自动索引 profile 。 支持Vercel/Next.js,Express,以及自定义框架.

Vercel / Next.js App 路由器

// app/api/webhook/route.ts
import { createVercelHandler } from "@augmentcode/context-connectors/integrations/vercel";
import { S3Store } from "@augmentcode/context-connectors/stores";

const store = new S3Store({ bucket: process.env.INDEX_BUCKET! });

export const POST = createVercelHandler({
  store,
  secret: process.env.GITHUB_WEBHOOK_SECRET!,

  // Only index main branch
  shouldIndex: (event) => event.ref === "refs/heads/main",

  // Log results
  onIndexed: (key, result) => {
    console.log(`Indexed ${key}: ${result.filesIndexed} files`);
  },
});

快递

import express from "express";
import { createExpressHandler } from "@augmentcode/context-connectors/integrations/express";
import { FilesystemStore } from "@augmentcode/context-connectors/stores";

const app = express();
const store = new FilesystemStore({ basePath: "./indexes" });

// Must use raw body for signature verification
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  createExpressHandler({
    store,
    secret: process.env.GITHUB_WEBHOOK_SECRET!,
  })
);

app.listen(3000);

自定义框架

import {
  createGitHubWebhookHandler,
  verifyWebhookSignature
} from "@augmentcode/context-connectors/integrations";
import { S3Store } from "@augmentcode/context-connectors/stores";

const store = new S3Store({ bucket: "my-indexes" });
const handler = createGitHubWebhookHandler({ store, secret: "..." });

// In your request handler:
async function handleRequest(req: Request) {
  const signature = req.headers.get("x-hub-signature-256")!;
  const eventType = req.headers.get("x-github-event")!;
  const body = await req.text();

  if (!await verifyWebhookSignature(body, signature, secret)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const result = await handler(eventType, JSON.parse(body));
  return Response.json(result);
}

GitHub 应用程序设置

1. 转到 设置 > 开发者设置 > GitHub Apps > 新建 GitHub App
2. 将 Webhook URL 设定为您的部署处理器
3. 生成并保存 Webhook 秘密
4. 设定 仓库内容 权限 读取
5. 订阅 推开 事件
6. 在您的仓库上安装应用程序

环境变量

数据存储

默认情况下,索引存储于 ~/.augment/context-connectors/ 在所有的平台上.

此位置与其他增强的 CLI 状态一致 :

• ~/.augment/session.json - 认证
• ~/.augment/settings.json - 用户设置
• ~/.augment/rules/ - 用户规则
• ~/.augment/agents/ - 用户定义的代理
• ~/.augment/commands/ - 自定义命令

覆盖 --store-path 或 CONTEXT_CONNECTORS_STORE_PATH 环境变量.

建筑

Sources → Indexer → Stores → Clients

• 来源: 从数据源获取文件( GitHub, GitLab, BitBucket, Website)
• 索引器: Orchestrates 使用 Augment 上下文引擎索引
• 存储: 持久性指数状态(Filesystem, S3)
• 客户: 控制索引( CLI, Agent, MCP 服务器通过 stdio 或 HTTP)

过滤

文件根据 :

1. .augmentignore - 自定义忽略模式(最高优先级)
2. 内建过滤器 - 二进制文件、大文件、生成代码、机密
3. .gitignore - 标准基特忽略模式

创建一个 .augmentignore 要自定义的文件 :

# Ignore test fixtures
tests/fixtures/

# Ignore generated docs
docs/api/

# Ignore specific files
config.local.json

说明: 这个 .augmentignore 文件必须放在 源根目录 (路径传递到添加命令),而不是当前工作目录.

网站来源

网站源会爬行并索引静态的HTML内容.

限制

• JavaScript 递归的内容不支持. 只有静态的 HTML 被爬行 。 需要JavaScript渲染内容的单页应用程序(SPA)或页面将不会被完全索引.
• 仅基于链接的爬行 - 页面必须能够从起始的 URL 通过链接被发现 .

S3-可兼容存储

当使用MinIO, DigitalOcean Spaces 或 Backflaze B2 等S3兼容服务时,通过环境变量配置:

export CC_S3_BUCKET=my-bucket
export CC_S3_ENDPOINT=http://localhost:9000
export CC_S3_FORCE_PATH_STYLE=true
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin

npx context-connectors index github --owner myorg --repo myrepo -i my-project --store s3

许可证

麻省理工学院