Akyn Ai

akyn-ai

在 5 分钟内将任意数据源变成 MCP 服务。

构建 Claude 和 Cursor 等 AI 助手可以直接查询的知识库。无需基础设施。

---

这是什么？

此 SDK 可让你根据任意数据源创建 MCP（Model Context Protocol） 服务。你的文档、PDF、网站或任何文本都可以变成可查询的知识库，供 AI 助手直接访问。

使用场景：

• 📚 让 Cursor/Claude 可以搜索你的文档
• 🔍 构建 RAG（检索增强生成）流水线
• 🤖 创建具备领域知识的自定义 AI 助手
• 📖 为研究论文、指南或任何文本内容建立索引

---

快速开始

安装

npm install akyn-ai

基本用法

import { KnowledgeBase } from 'akyn-ai'

// Create a knowledge base
const kb = new KnowledgeBase({
  name: 'my-docs',
  description: 'My project documentation',
})

// Add your content
await kb.addDirectory('./docs')           // Add all docs from a folder
await kb.addFile('./README.md')           // Add a specific file
await kb.addURL('https://docs.example.com') // Scrape a URL
await kb.addText('Important info here')   // Add raw text

// Serve as MCP server
kb.serveStdio()  // For Cursor/Claude Desktop

连接到 Cursor

添加到你的 .cursor/mcp.json：

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["ts-node", "./my-kb.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

连接到 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["ts-node", "/path/to/my-kb.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

---

功能

📁 多来源导入

// Files (PDF, DOCX, TXT, Markdown)
await kb.addFile('./guide.pdf')
await kb.addFile('./manual.docx')

// Directories (recursive)
await kb.addDirectory('./docs', {
  recursive: true,
  extensions: ['.md', '.txt', '.pdf'],
})

// URLs
await kb.addURL('https://docs.example.com')
await kb.addURLs([
  'https://example.com/page1',
  'https://example.com/page2',
])

// Raw text
await kb.addText('Custom content here', 'My Notes')

🔍 智能分块

文本会自动拆分为适合嵌入的最佳块：

const kb = new KnowledgeBase({
  name: 'my-kb',
  chunking: {
    maxSize: 1000,    // Max characters per chunk
    overlap: 200,     // Overlap between chunks for context
  },
})

🧠 灵活的嵌入

默认使用 OpenAI，但你也可以使用自己的嵌入模型：

import { KnowledgeBase, type EmbeddingsProvider } from 'akyn-ai'

// Use OpenAI (default)
const kb = new KnowledgeBase({ name: 'my-kb' })

// Or customize OpenAI settings
import { OpenAIEmbeddings } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  embeddings: new OpenAIEmbeddings({
    model: 'text-embedding-3-large',  // Better quality
    apiKey: 'sk-...',
  }),
})

// Or bring your own provider
class MyEmbeddings implements EmbeddingsProvider {
  readonly dimensions = 384
  
  async embed(text: string) {
    // Your embedding logic here
    return { embedding: [...], tokenCount: 100 }
  }
  
  async embedBatch(texts: string[]) {
    return Promise.all(texts.map(t => this.embed(t)))
  }
}

const kb = new KnowledgeBase({
  name: 'my-kb',
  embeddings: new MyEmbeddings(),
})

💾 向量存储

内存存储（默认）

非常适合开发和小型数据集：

import { InMemoryVectorStore } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new InMemoryVectorStore({
    persistPath: './kb-data.json',  // Optional: save to disk
  }),
})

Qdrant

对于生产工作负载，可使用高性能向量数据库 Qdrant：

import { KnowledgeBase, QdrantVectorStore } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new QdrantVectorStore(),  // That's it!
})

本地设置（Docker）

# Start Qdrant with one command
docker run -p 6333:6333 qdrant/qdrant

# With persistent storage
docker run -p 6333:6333 -v ./qdrant_data:/qdrant/storage qdrant/qdrant

Qdrant Cloud

如需托管服务，可使用 Qdrant Cloud：

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new QdrantVectorStore({
    url: 'https://your-cluster.cloud.qdrant.io',
    apiKey: process.env.QDRANT_API_KEY,
    collection: 'my-docs',  // Optional: defaults to 'akyn_documents'
  }),
})

选项	类型	默认值	说明
url	string	http://localhost:6333	Qdrant 服务 URL
apiKey	string	-	API 密钥（Qdrant Cloud 必填）
collection	string	akyn_documents	集合名称
dimensions	number	自动检测	向量维度

自定义向量存储

为其他数据库（Pinecone、Weaviate 等）实现 VectorStore 接口：

import type { VectorStore } from 'akyn-ai'

class MyVectorStore implements VectorStore {
  async add(document) { /* ... */ }
  async addBatch(documents) { /* ... */ }
  async search(embedding, options) { /* ... */ }
  async delete(id) { /* ... */ }
  async clear() { /* ... */ }
  async count() { /* ... */ }
}

🌐 多种传输选项

// Stdio (for Cursor/Claude Desktop)
kb.serveStdio()

// HTTP (for web clients)
await kb.serveHttp({ port: 3000 })

---

CLI 用法

你也可以使用 CLI，无需编写代码：

# Index a directory
npx akyn-ai --dir ./docs --name "My Docs"

# Use a config file
npx akyn-ai --config ./kb-config.json

# Run as HTTP server
npx akyn-ai --dir ./docs --http 3000

配置文件格式

{
  "name": "My Knowledge Base",
  "description": "Project documentation",
  "sources": [
    { "type": "directory", "path": "./docs" },
    { "type": "file", "path": "./README.md" },
    { "type": "url", "url": "https://docs.example.com" }
  ]
}

---

API 参考

KnowledgeBase

用于创建和管理知识库的主类。

const kb = new KnowledgeBase({
  name: string,           // Required: Name of the knowledge base
  description?: string,   // Optional: Description
  version?: string,       // Optional: Version (default: '1.0.0')
  embeddings?: EmbeddingsProvider,  // Optional: Custom embeddings
  vectorStore?: VectorStore,        // Optional: Custom vector store
  chunking?: ChunkOptions,          // Optional: Chunking settings
  retrieval?: RetrievalOptions,     // Optional: Retrieval settings
})

检索选项

控制返回的结果数量及其最低质量。这些选项在代码中配置（不会暴露给 AI Agent），让你完全掌控检索行为。

const kb = new KnowledgeBase({
  name: 'my-kb',
  retrieval: {
    topK: 10,         // Return up to 10 chunks per query
    threshold: 0.5,   // Only return chunks with similarity score >= 0.5
  },
})

选项	类型	默认值	说明
topK	number	5	每次查询最多检索的块数
threshold	number	0	最低相似度分数（0-1）。设为 0 将返回所有结果；设为更高的值（例如 0.5、0.7）则会过滤掉相关性较低的块

方法

方法	说明
addText(text, name?)	添加原始文本内容
addFile(path, name?)	添加文件（PDF、DOCX、TXT、MD）
addDirectory(path, options?)	添加目录中的所有文件
addURL(url, name?)	添加 URL 中的内容
addURLs(urls)	添加多个 URL
query(question, options?)	查询知识库
listSources()	列出所有已建立索引的来源
serveStdio(options?)	启动 stdio MCP 服务
serveHttp(options?)	启动 HTTP MCP 服务

HTTP 服务选项

await kb.serveHttp({
  port: 3000,           // Port to listen on (default: 3000)
  host: '0.0.0.0',      // Host to bind to (default: '0.0.0.0')
  cors: true,           // Enable CORS (default: true)
  corsOrigin: '*',      // CORS origin (default: '*')
  debug: false,         // Enable debug logging (default: false)
})

实用工具

SDK 还导出了可独立使用的实用工具：

import {
  // Text processing
  normalizeText,
  chunkText,
  extractTextFromHTML,
  stripMarkdown,
  
  // File loading
  loadFile,
  loadDirectory,
  loadURL,
  
  // Embeddings
  OpenAIEmbeddings,
  cosineSimilarity,
  
  // Vector stores
  InMemoryVectorStore,
  QdrantVectorStore,
} from 'akyn-ai'

---

MCP 工具

通过 MCP 连接时，你的知识库会提供以下工具：

query

使用自然语言问题搜索知识库。

{
  "name": "query",
  "arguments": {
    "question": "How do I authenticate?"
  }
}

参数	类型	描述
question	字符串	要搜索的问题

注意： 结果数量和相似度阈值通过创建 KnowledgeBase 时的 retrieval 选项配置。请参阅检索选项。

list_sources

列出知识库中所有已索引的来源。

{
  "name": "list_sources",
  "arguments": {}
}

---

示例

更多内容请参阅示例目录：

• 基本用法
• HTTP 服务
• 自定义嵌入
• Qdrant 向量存储

---

要求

• Node.js 18+
• OpenAI API 密钥（或自定义嵌入提供方）

---

想要托管服务？

想打造更大的项目？请访问 Akyn：

• ☁️ 托管知识库
• 👥 团队协作
• 📊 使用情况分析
• 💰 盈利（对查询收费）
• 🔐 API 密钥管理

---

贡献

欢迎贡献！请先阅读我们的贡献指南。

---

许可证

MIT © Akyn AI