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 エージェントには公開されません）、検索動作を完全に制御できます。

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	string	検索する質問

注記： 結果の数と類似度のしきい値は、KnowledgeBase の作成時に retrieval オプションで設定します。Retrieval Options を参照してください。

list_sources

ナレッジベース内でインデックス化されたすべてのソースを一覧表示します。

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

---

例

詳しくは、examples ディレクトリをご覧ください。

• 基本的な使い方
• HTTP サーバー
• カスタム埋め込み
• Qdrant ベクトルストア

---

要件

• Node.js 18+
• OpenAI API キー（またはカスタム埋め込みプロバイダー）

---

マネージドホスティングをご希望ですか？

より大規模なものを構築していますか？Akyn をご覧ください。

• ☁️ ホスト型ナレッジベース
• 👥 チームでのコラボレーション
• 📊 使用状況の分析
• 💰 収益化（クエリに課金）
• 🔐 API キー管理

---

コントリビューション

コントリビューションを歓迎します！まず、コントリビューションガイドラインをお読みください。

---

ライセンス

MIT © Akyn AI