# MCP Knowledge Server

A production-ready **Remote Model Context Protocol (MCP) Server** built with **Cloudflare Workers** that provides AI assistants with fast, structured, read-only access to Markdown knowledge stored in GitHub.

Instead of searching raw Markdown files on every request, the server indexes document metadata into Cloudflare KV, enabling low-latency retrieval while keeping hosting costs minimal.

---

## Features

- Remote MCP Server
- Cloudflare Workers deployment
- GitHub-backed knowledge base
- Multi-profile isolation
    - Company
    - Personal
    - Freelance
- Metadata indexing
- KV caching
- Stateless architecture
- Fast keyword search
- Markdown document retrieval
- Bearer token authentication
- Cron-based index rebuilding
- Manual reindex support

---

## Architecture

```
                 GitHub Repository

          company/
          personal/
          freelance/
                 │
                 ▼
          manifest.json
                 │
                 ▼
      Cloudflare Worker
                 │
     ┌───────────┴───────────┐
     │                       │
Search Index           Document Fetch
     │                       │
     ▼                       ▼
Cloudflare KV          GitHub Raw Files
     │
     ▼
   MCP Client
(Cursor / Claude / VS Code)
```

---

## Knowledge Structure

```
company/
    projects/
    skills/
    glossary/
    architecture/
    troubleshooting/
    manifest.json

personal/
    ...

freelance/
    ...
```

Every Markdown document contains structured frontmatter:

```yaml
---
id: project-mcp
title: MCP Knowledge Server
type: project

tags:
    - mcp
    - cloudflare

keywords:
    - retrieval
    - markdown

summary: Remote MCP server powered by Cloudflare Workers.

priority: 1

updated_at: 2026-07-01
---
```

---

## MCP Tools

### list_profiles

Returns all available knowledge profiles.

```
company
personal
freelance
```

---

### search_knowledge

Search metadata across a selected profile.

Example:

```json
{
	"profile": "personal",
	"query": "cloudflare workers",
	"limit": 5
}
```

Returns

- title
- summary
- tags
- related documents
- confidence
- document id

---

### get_document

Retrieve the complete Markdown document.

```json
{
	"profile": "company",
	"id": "proj-mcp-server"
}
```

---

### reindex_profile

Rebuild the search index from the latest GitHub manifest.

---

## Why Metadata Indexing?

Searching raw Markdown for every request quickly becomes expensive.

Instead:

```
Markdown Files
       │
       ▼
manifest.json
       │
       ▼
Metadata Index
       │
       ▼
Cloudflare KV
       │
       ▼
Instant Search
```

Only the requested document is fetched from GitHub.

---

## Tech Stack

- Cloudflare Workers
- Model Context Protocol (MCP)
- Cloudflare KV
- TypeScript
- Zod
- GitHub Raw Content
- Wrangler
- GitHub Actions

---

## Project Structure

```
src/
 ├── cache/
 ├── fetcher/
 ├── indexer/
 ├── mcp/
 │    ├── tools/
 │    └── server.ts
 ├── registry/
 ├── types.ts
 └── index.ts
```

---

## Local Development

```bash
pnpm install

wrangler dev
```

Inspect the server:

```bash
npx @modelcontextprotocol/inspector
```

---

## Deployment

```bash
wrangler deploy
```

---

## Security

The server uses Bearer Token authentication.

```http
Authorization: Bearer <TOKEN>
```

---

## Roadmap

### Version 1

- Metadata indexing
- GitHub integration
- KV cache
- MCP tools
- Profile isolation

### Version 2

- Vector Search
- Semantic search
- OAuth
- Multi-user support
- Relationship graph
- Fuzzy search

---

## Design Goals

- Fast
- Stateless
- Low-cost
- Production-ready
- Easy to maintain
- AI-friendly
- Cloud-native

---