Which integrations are available for this server?

Provides integration with OpenAI embeddings for vectorizing text chunks, enabling semantic search.

How do I use akyn-ai?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@akyn-ai index my project's README.md as a knowledge base" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

akyn-ai

by IlyesTal

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Hybrid

akyn-ai

Turn any data source into an MCP server in 5 minutes.

Build knowledge bases that AI assistants like Claude and Cursor can query directly. No infrastructure needed.

npm version License: MIT

What is this?

This SDK lets you create MCP (Model Context Protocol) servers from any data source. Your docs, PDFs, websites, or any text can become a queryable knowledge base that AI assistants can access directly.

Use cases:

📚 Make your documentation searchable by Cursor/Claude
🔍 Build RAG (Retrieval-Augmented Generation) pipelines
🤖 Create custom AI assistants with domain knowledge
📖 Index research papers, guides, or any text content

Related MCP server: MindOS

Quick Start

Install

npm install akyn-ai

Basic Usage

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

Connect to Cursor

Add to your .cursor/mcp.json:

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

Connect to Claude Desktop

Add to ~/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-..."
      }
    }
  }
}

Features

📁 Multi-Source Ingestion

// 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')

🔍 Smart Chunking

Text is automatically split into optimal chunks for embedding:

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

🧠 Flexible Embeddings

Uses OpenAI by default, but you can bring your own:

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(),
})

💾 Vector Stores

In-Memory (Default)

Perfect for development and small datasets:

import { InMemoryVectorStore } from 'akyn-ai'

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

Qdrant

For production workloads, use Qdrant - a high-performance vector database:

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

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

Local Setup (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

For managed hosting, use 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'
  }),
})

Option	Type	Default	Description
`url`	string	`http://localhost:6333`	Qdrant server URL
`apiKey`	string	-	API key (required for Qdrant Cloud)
`collection`	string	`akyn_documents`	Collection name
`dimensions`	number	auto-detected	Vector dimensions

Custom Vector Store

Implement the VectorStore interface for other databases (Pinecone, Weaviate, etc.):

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() { /* ... */ }
}

🌐 Multiple Transport Options

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

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

CLI Usage

You can also use the CLI without writing code:

# 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

Config File Format

{
  "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 Reference

`KnowledgeBase`

Main class for creating and managing knowledge bases.

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
})

Retrieval Options

Control how many results are returned and their minimum quality. These options are configured in your code (not exposed to AI agents), giving you full control over retrieval behavior.

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
  },
})

Option	Type	Default	Description
`topK`	number	5	Maximum number of chunks to retrieve per query
`threshold`	number	0	Minimum similarity score (0-1). Set to `0` to return all results, or higher (e.g. `0.5`, `0.7`) to filter out less relevant chunks

Methods

Method	Description
`addText(text, name?)`	Add raw text content
`addFile(path, name?)`	Add a file (PDF, DOCX, TXT, MD)
`addDirectory(path, options?)`	Add all files from a directory
`addURL(url, name?)`	Add content from a URL
`addURLs(urls)`	Add multiple URLs
`query(question, options?)`	Query the knowledge base
`listSources()`	List all indexed sources
`serveStdio(options?)`	Start stdio MCP server
`serveHttp(options?)`	Start HTTP MCP server

HTTP Server Options

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)
})

Utilities

The SDK also exports utilities you can use independently:

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

MCP Tools

When connected via MCP, your knowledge base exposes these tools:

`query`

Search the knowledge base with a natural language question.

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

Parameter	Type	Description
`question`	string	The question to search for

Note: The number of results and similarity threshold are configured via the retrieval option when creating the KnowledgeBase. See Retrieval Options.

`list_sources`

List all indexed sources in the knowledge base.

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

Examples

See the examples directory for more:

Requirements

Node.js 18+
OpenAI API key (or custom embeddings provider)

Want Managed Hosting?

Building something bigger? Check out Akyn for:

☁️ Hosted knowledge bases
👥 Team collaboration
📊 Usage analytics
💰 Monetization (charge for queries)
🔐 API key management

Contributing

Contributions welcome! Please read our contributing guidelines first.

License

MIT © Akyn AI

Available Tools

2 tools

list_sourcesB

List all sources (documents, URLs) indexed in the "Knowledge Base" knowledge base

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It states a basic read action but does not disclose behavior such as pagination, sorting, return format, or any limits. It is a minimal description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that directly conveys the tool's purpose without redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no parameters, no output schema), so the description covers the basic scope. However, it lacks any indication of what the output looks like or any additional context that would help the agent fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter details, and it avoids unnecessary information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: listing all sources (documents, URLs) indexed in the Knowledge Base. It uses a specific verb and resource, but does not explicitly distinguish itself from the sibling tool 'query'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the 'query' tool. There is no mention of scenarios, prerequisites, or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryA

Query the "Knowledge Base" knowledge base with a natural language question. Returns relevant context chunks from the indexed content.

ParametersJSON Schema

Name	Required	Description	Default
`question`	Yes	The question to search for in the knowledge base

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool 'Returns relevant context chunks from the indexed content,' which informs the agent of the return behavior. However, it does not mention potential limitations, error handling, or whether the operation is strictly read-only. For a simple query tool this is adequate but not richly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and every word earns its place. It front-loads the core action and resource, then immediately states the return value. There is no redundant information or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and no output schema, the description covers the essential aspects: what it does, what input it takes, and what it returns. It lacks detail on response size or potential pagination, but given the simplicity of the tool, the description is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a clear description for the 'question' parameter ('The question to search for in the knowledge base'). The tool description adds the nuance that this is a 'natural language question,' clarifying that the agent can formulate queries in everyday language rather than requiring specific keywords. This adds meaning beyond the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Query the Knowledge Base knowledge base with a natural language question.' It specifies the verb (Query), the resource (Knowledge Base), and the expected output (relevant context chunks). This differentiates it from the sibling tool 'list_sources' which lists sources rather than performing semantic queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when you have a natural language question about the knowledge base. It does not explicitly mention alternatives or when not to use it, but the use case is evident from the phrasing. For a single-purpose query tool with a sibling that lists sources, this level of guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.1.15Aug 9, 2026
- First observedlist_sources
- First observedquery

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored 2026-08-09 14:00 across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: query retrieves context from the knowledge base, while list_sources enumerates indexed sources. No overlap or ambiguity exists between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern: 'query' and 'list_sources'. The naming is predictable and aligned with the server's domain.

Tool Count3/5

With only two tools, the set feels thin for a knowledge base server, but it covers the core query and source-listing operations. It is on the borderline of being too minimal but not egregiously so.

Completeness3/5

The server provides only read-oriented operations (query and list_sources). Missing source management capabilities such as adding, updating, or deleting sources represent notable gaps for a complete knowledge base lifecycle, though the core query functionality is present.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

anythingmcp A
io.github.keysersoft
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
Agent Orchestration Data Platforms App Automation
42197
Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
219
driflyte-mcp-server
com.driflyte
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Search Web Scraping Knowledge & Memory
211
gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361

Related MCP Servers

CentralMind/Gateway
Databases RAG Systems Developer Tools
centralmind
A
license
Not graded
quality
B
maintenance
MCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB
Updated a year ago (2025-07-18 16:15 UTC)
548
Apache 2.0
MindOS
Knowledge & Memory Note Taking File Systems
GeminiLight
A
license
Not graded
quality
A
maintenance
Local-first knowledge base MCP server. Lets AI agents (Claude Code, Cursor, etc.) read and write your personal knowledge base through 20 MCP tools. Zero cloud dependency — all files stay on your machine.
Updated an hour ago (2026-09-10 21:11 UTC)
1,758
667
MIT
mcpolyglot
Databases Developer Tools
ishay60
A
license
Not graded
quality
C
maintenance
One config, one CLI that turns your databases (Postgres, MySQL, SQLite, MongoDB) into MCP servers for Claude, GPT, Cursor, and any MCP-compatible agent.
Updated a month ago (2026-08-03 09:18 UTC)
1
MIT
MCP-Maker
Databases Search Developer Tools
MrAliHasan
A
license
Not graded
quality
B
maintenance
Auto-generates MCP servers from any data source, enabling AI clients to query databases, spreadsheets, and APIs with zero code.
Updated 2 months ago (2026-07-18 20:20 UTC)
5
MIT

akyn-ai

What is this?

Quick Start

Install

Basic Usage

Connect to Cursor

Connect to Claude Desktop

Features

📁 Multi-Source Ingestion

🔍 Smart Chunking

🧠 Flexible Embeddings

💾 Vector Stores

In-Memory (Default)

Qdrant

Custom Vector Store

🌐 Multiple Transport Options

CLI Usage

Config File Format

API Reference

KnowledgeBase

Retrieval Options

Methods

HTTP Server Options

Utilities

MCP Tools

query

list_sources

Examples

Requirements

Want Managed Hosting?

Contributing

License

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

CentralMind/Gateway

MindOS

mcpolyglot

MCP-Maker

`KnowledgeBase`

`query`

`list_sources`