# Knowledge Base MCP Server

A lightweight personal knowledge base server built with [FastMCP](https://github.com/jlowin/fastmcp). It lets an MCP-compatible client store, search, organize, and summarize research notes from a local JSON file.

## Features

- Add structured notes with titles, content, tags, and timestamps
- Search notes by keyword across titles and content
- Filter notes by tag
- List all tags used in the knowledge base
- Delete notes by ID
- View knowledge base statistics, including tag distribution and content depth
- Expose recent notes and statistics as MCP resources
- Provide a reusable research-summary prompt for synthesizing saved notes
- Include an optional `.claude` research-capture skill for guided note capture workflows

## Project Structure

```text
.
|-- server.py
|-- notes.json
|-- requirements.txt
`-- .claude/
    `-- skills/
        `-- research-capture/
            `-- SKILL.md
```

## Requirements

- Python 3.10 or newer
- An MCP-compatible client such as Claude Desktop, Codex, Cursor, or another client that can launch local MCP servers

## Installation

Clone the repository and install the Python dependency:

```bash
git clone https://github.com/YOUR_USERNAME/knowledge-base-mcp.git
cd knowledge-base-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

On macOS or Linux, activate the virtual environment with:

```bash
source .venv/bin/activate
```

## Running the Server

Run the MCP server directly:

```bash
python server.py
```

The server uses stdio transport by default through `mcp.run()`, which is the common setup for local MCP clients.

## MCP Client Configuration

Add a server entry to your MCP client configuration. Use the absolute path to `server.py` on your machine.

Example:

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["C:\\Users\\YOUR_NAME\\path\\to\\knowledge-base-mcp\\server.py"]
    }
  }
}
```

If you use a virtual environment, point the command to the virtual environment's Python executable:

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "C:\\Users\\YOUR_NAME\\path\\to\\knowledge-base-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YOUR_NAME\\path\\to\\knowledge-base-mcp\\server.py"]
    }
  }
}
```

## Available Tools

| Tool | Description |
| --- | --- |
| `add_note` | Add a note with a title, content, and optional tags |
| `search_notes` | Search note titles and content by keyword |
| `get_notes_by_tag` | Return notes that contain a specific tag |
| `list_tags` | List all unique tags in the knowledge base |
| `delete_note` | Delete a note by numeric ID |
| `get_statistics` | Return note count, tag distribution, date range, and average content length |

## Available Resources

| Resource | Description |
| --- | --- |
| `notes://recent` | Shows the five most recent notes |
| `notes://stats` | Shows formatted knowledge base statistics |

## Available Prompt

| Prompt | Description |
| --- | --- |
| `research_summary(topic)` | Creates a structured research summary workflow for a topic |

## Data Storage

Notes are stored in `notes.json` next to `server.py`. Each note uses this structure:

```json
{
  "id": 1,
  "title": "Example note",
  "content": "The note body goes here.",
  "tags": ["example", "research"],
  "created_at": "2026-05-09T20:26:50.618981"
}
```

Before publishing a public repository, review `notes.json` and remove any private or sensitive information.

## Example Usage

After connecting the server to an MCP client, you can ask the client to:

- "Add a note about MCP authentication updates with tags MCP and security."
- "Search my notes for OAuth."
- "Show all notes tagged research."
- "List my knowledge base tags."
- "Create a research summary about MCP architecture."

## Development

The project is intentionally small:

- `server.py` contains the MCP server, tools, resources, and prompt.
- `notes.json` is the local JSON data store.
- `.claude/skills/research-capture/SKILL.md` defines an optional workflow for capturing and reviewing research notes.

To check that the server imports correctly:

```bash
python -m py_compile server.py
```

## License
MIT