# ObsidianKB MCP Server

Git-backed MCP server for creating and maintaining an Obsidian-style markdown knowledge base.

## Implemented Scope

- Full MCP toolset: `kb_create`, `kb_search`, `kb_get`, `kb_update`, `kb_list`, `kb_delete`, `kb_sync`
- Seven skills and templates: bug report, API doc, component doc, changelog, ADR, guide, runbook
- Frontmatter-aware markdown read/write and path safety checks
- MiniSearch indexing with filters and field boosting
- Git pull/commit/push workflow
- `obsidian-kb-mcp init [path]` scaffold command
- CI workflow (`.github/workflows/validate.yml`)

## Requirements

- Node.js 20+
- Git installed and configured

## Installation

```bash
npm install
npm run build
```

## Usage

Run as MCP server (stdio transport):

```bash
node dist/index.js
```

Initialize a vault scaffold:

```bash
node dist/index.js init ./my-kb
```

## Configuration

Create `obsidian-kb.config.json` in the runtime working directory:

```json
{
  "vault_path": "/absolute/path/to/obsidian-kb",
  "remote": "origin",
  "default_branch": "main",
  "auto_pull_before_read": true,
  "auto_push_after_write": true,
  "default_author": "your-github-username",
  "commit_prefix": "[kb]",
  "search": {
    "boost": {
      "title": 3,
      "tags": 2,
      "body": 1
    },
    "fuzzy": 0.2
  }
}
```

Environment overrides:

- `OBSIDIAN_KB_VAULT_PATH`
- `OBSIDIAN_KB_AUTHOR`
- `OBSIDIAN_KB_AUTO_PUSH`

## Scripts

- `npm run dev` - run server in tsx
- `npm run build` - bundle with tsup
- `npm run lint` - biome check
- `npm run format` - biome format
- `npm test` - vitest

## MCP client example (Cursor)

```json
{
  "mcpServers": {
    "obsidian-kb": {
      "command": "node",
      "args": ["/absolute/path/to/obsidianKB/dist/index.js"],
      "env": {
        "OBSIDIAN_KB_VAULT_PATH": "/absolute/path/to/obsidian-vault",
        "OBSIDIAN_KB_AUTHOR": "your-github-username"
      }
    }
  }
}
```