aik-mcp

aik-mcp is an MCP server that turns a directory of Markdown files into a queryable knowledge base for any MCP-compatible AI agent — opencode, Claude Code, Cline, and others.

Write rules, skills, workflows, and templates as plain Markdown files with frontmatter. Your AI agent can then discover, read, search, and install them at runtime.

Table of Contents

• Installation

• Quick start

• Client configuration

  • opencode

  • Claude Code

  • Cline

• Environment

• CLI options

• MCP tools

• Resources

• Content structure

• Development

• Contributing

• License

Related MCP server: MinerU Document Explorer

Installation

# Run directly (no install)
npx aik-mcp

# Install globally
npm install -g aik-mcp
aik-mcp

# From a local build
git clone https://github.com/openhoat/aik-mcp.git
cd aik-mcp
npm install
npm run build

Quick start

1. Create a content directory

mkdir -p my-knowledge/rules my-knowledge/skills my-knowledge/workflows

2. Add a rule

cat > my-knowledge/rules/typescript.md << 'EOF'
---
title: TypeScript Conventions
description: Coding standards for TypeScript projects
tags: [typescript, conventions]
version: "1.0.0"
compatibility: [opencode, claude-code, cline]
---

# TypeScript Conventions

- Use explicit types for public API surfaces
- Prefer `interface` over `type` for object shapes
- Use `const` assertions for literal values
EOF

3. Start the server

AIK_CONTENT_DIR=./my-knowledge aik-mcp

4. Configure your AI agent

See Client configuration below.

5. Ask your agent

Once connected, your agent can use tools like aik_search and aik_get to find and apply your knowledge.

Client configuration

opencode

Add to your project's .mcp.json:

{
  "mcpServers": {
    "aik": {
      "command": "npx",
      "args": ["aik-mcp"],
      "env": {
        "AIK_CONTENT_DIR": "/path/to/your/content",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json (or ~/.claude/settings.json for global use):

{
  "mcpServers": {
    "aik": {
      "command": "npx",
      "args": ["aik-mcp"],
      "env": {
        "AIK_CONTENT_DIR": "/path/to/your/content",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Cline

Add to your cline.json or project .mcp.json:

{
  "mcpServers": {
    "aik": {
      "command": "npx",
      "args": ["aik-mcp"],
      "env": {
        "AIK_CONTENT_DIR": "/path/to/your/content",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Tip: Set AIK_CONTENT_DIR to a shared location (Dropbox, git repo, etc.) to use the same knowledge base across projects and agents.

Environment

CLI options

MCP tools

Resources

• aik://{category} — list items in a category (e.g. aik://rules)

• aik://search?q=... — search items by keyword

When working on a task

1. Use aik_list or aik_search to find relevant content

2. Use aik_get to read specific items

3. Apply the relevant rules, follow the workflows, and invoke skills as needed

Content structure

Content items are organized by category:

Adding content

Create a .md file with frontmatter in the appropriate category directory:

---
title: "My Rule"
description: "Description of the rule"
tags: [tag1, tag2]
version: "1.0.0"
compatibility: [opencode, claude-code, cline]
---

# My Rule

Content here...

Development

npm install
npm run build
npm run test
npm run qa

Commands reference

Contributing

Contributions are welcome! Please open an issue or submit a PR.

See the changelog for release history.

License

MIT