---
icon: lucide/rocket
---

# Personal MCP

This project is a document library of software patterns, best practices, and structured references to external documentation. The same markdown files are published through two equivalent surfaces, so human-readable docs and MCP resources stay aligned.

## MCP Server

An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` provides context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), such as VS Code.

## Docs

A website at `/docs` for humans to read and review.

## Quick start

Install dependencies first:

```bash
uv sync
```

Run the app locally with the static docs rebuilt first:

```bash
uv run zensical build && uv run uvicorn personal_mcp.main:app --host 127.0.0.1 --port 8765
```

Build and run the Docker image with the same exposed port:

```bash
docker build -t personal-mcp . && docker run --rm -p 8765:8765 personal-mcp
```

When the server is running, the health check is available at `/healthz` and the generated docs are available at `/docs/`.

## Architecture

- [Resource-First Pattern Module Architecture](./architecture.md)
- [Content Contract](./content.md)
- [Frontmatter Contract](./frontmatter.md)
- [URI Contract](./uris.md)
- [Static Docs Hosting Pattern](./mcp_layout.md)
- [Skill Usage Mechanics](./usage.md)
- [Copilot MCP Mechanics](./copilot.md)