KOmcp

Kura Notes管理的远程MCP服务器

![License: MIT](https://opensource.org/licenses/MIT) ![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/)

______________________________________________________________________

概述

KOmcp是一个独立的远程MCP（模型上下文协议）服务器，使Claude和其他LLM应用程序能够安全地 创建、搜索、检索和管理Kura笔记 通过OAuth2-身份验证的API调用。

什么是MCP？

这模型上下文协议（MCP）是Anthropic开发的一个开放标准，用于将AI助手连接到外部数据源和工具。KOmcp实现了这个协议，将Kura的语义搜索作为Claude可以使用的工具。

主要特点

✅ MCP协议合规性： 实施MCP规范（2025-06-18）
🔒 OAuth2身份验证： 与KOauth集成，实现基于令牌的安全身份验证
🔍 语义搜索： 利用Kura的矢量语义搜索
✏️ 完整的CRUD操作： 通过Kura API创建、读取、列出和删除注释
🚀 克劳德网络连接器： 与Claude的自定义连接器功能无缝配合
🐳 Docker部署： 生产就绪的集装箱化部署
📊 类型安全： 使用TypeScript构建，具有可靠性和可维护性

______________________________________________________________________

建筑

┌─────────────┐         ┌──────────────┐         ┌─────────────┐         ┌─────────────┐
│   Claude    │────────▶│    KOmcp     │────────▶│   KOauth    │         │    Kura     │
│  (Web/App)  │  MCP    │  MCP Server  │  OAuth  │   OAuth2    │         │   Notes     │
│             │◀────────│   (HTTP)     │  Token  │   Server    │         │   API       │
└─────────────┘         └──────────────┘  Valid  └─────────────┘         └─────────────┘
                               │                                                  │
                               └──────────────────────────────────────────────────┘
                                    Full API Access (Search, CRUD)

组件

KOmcp（本项目）： MCP服务器将Kura操作作为MCP工具公开
KOauth： 用于身份验证的OAuth2服务器()
库拉： 带语义搜索和API的笔记制作应用
克劳德： 发现并使用工具的LLM客户端

______________________________________________________________________

技术栈

运行时间： Node.js 20（LTS）
语言： TypeScript 5.x（严格模式）
Web框架： 禁食4.x
数据库ORM： 棱镜5.x
数据库： PostgreSQL 15+，带pgvector扩展
MCP-SDK： @modelcontextprotocol/sdk （官方TypeScript SDK）
OAuth： JWT验证 jsonwebtoken + jwks-rsa
部署： Docker+Docker编写+Nginx

______________________________________________________________________

先决条件

Node.js： 20.x或更高
npm： 9.x或更高
KOauth： 运行支持RFC 7591（动态客户端注册）的OAuth2服务器
库拉： 在启用API的情况下运行Kura实例
Docker： （可选）用于集装箱化部署

______________________________________________________________________

快速开始

1.克隆存储库

git clone https://github.com/TillMatthis/KOmcp.git
cd KOmcp

2.安装依赖项

npm install

3.配置环境

复制 .env.example 到 .env 并配置：

cp .env.example .env

编辑 .env:

# Server
NODE_ENV=development
PORT=3003
HOST=0.0.0.0
BASE_URL=http://localhost:3003

# KOauth Integration
KOAUTH_URL=https://auth.example.com
KOAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json
KOAUTH_CLIENT_REGISTRATION_URL=https://auth.example.com/oauth/register

# Kura API
KURA_URL=https://kura.tillmaessen.de

# Security
ALLOWED_ORIGINS=https://claude.ai
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=60000

# Logging
LOG_LEVEL=info

4.启动开发服务器

npm run dev

服务器将于启动 http://localhost:3003

5.验证健康状况

curl http://localhost:3003/health

预期响应：

{
  "status": "healthy",
  "timestamp": "2025-12-01T12:00:00.000Z",
  "uptime": 123.45,
  "version": "1.0.0"
}

______________________________________________________________________

Docker部署

生产部署

使用Docker Compose构建和运行：

# Build and start
npm run docker:prod:build

# Or manually
docker-compose up -d --build

# View logs
npm run docker:logs

# Stop
npm run docker:stop

服务器将在 http://localhost:3003

Docker开发

使用热重载运行：

# Start development container
npm run docker:dev:build

# View logs
docker-compose -f docker-compose.dev.yml logs -f

更改为 src/ 将自动重新加载服务器。

Docker环境

创建 .env 文件（与快速入门步骤3相同），然后运行Docker。

Docker容器：

以非root用户身份运行（nodejs:1001）
使用多阶段构建以实现最小的图像大小
包括健康检查
资源限制：512MB RAM，1个CPU
自动重启

构建VPS部署

# Build production image
docker build -t komcp:latest .

# Tag for registry
docker tag komcp:latest registry.example.com/komcp:latest

# Push to registry
docker push registry.example.com/komcp:latest

看 docs/deployment-guide.md 有关Nginx和SSL的完整VPS部署说明。

______________________________________________________________________

用法

将KOmcp添加到Claude

打开克劳德（网络或桌面）
转到“设置”→ 集成→ 自定义连接器
点击“添加自定义连接器”
输入您的KOmcp服务器URL： https://mcp.example.com
通过KOauth完成OAuth2授权
克劳德将发现所有可用的库拉工具

在Claude中使用

连接后，您可以要求Claude：

搜索： “在我的笔记中搜索有关机器学习的信息”
创建： “为今天与团队的会议创建一个注释”
查看： “显示笔记xyz-123的全部内容”
列表： “我最近的笔记是什么？”
删除： “删除ID为abc-456的注释”

Claude将自动使用适当的工具来管理您的Kura笔记。

可用工具

`search_kura_notes`

使用语义相似性搜索库拉笔记。查找与搜索查询在概念上相关的注释，即使它们不包含确切的关键字。

参数：

query （字符串，必填）：自然语言搜索查询
limit （数字，可选）：最大结果（1-50，默认值：10）
min_similarity （数字，可选）：相似性阈值0-1（默认值：0.7）

例子：

Search for "docker deployment best practices"

`create_note`

在Kura中创建一个包含内容、可选标题、注释和标签的新笔记。

参数：

content （字符串，必填）：备注内容（最多100000个字符）
title （字符串，可选）：注释标题（如果未提供，则自动生成）
annotation （字符串，可选）：附加上下文或元数据
tags （字符串数组，可选）：组织标签
contentType （字符串，可选）：内容类型提示（默认值：“text”）

例子：

Create a note with content "Deploy using docker-compose up -d",
title "Docker Deployment", and tags ["docker", "devops"]

`get_note`

通过特定笔记的ID检索其全部内容。

参数：

note_id （string，必填）：钞票的唯一ID

例子：

Get note with ID "abc-123-def-456"

`list_recent_notes`

列出最近创建或更新的20个笔记（摘要视图，没有完整内容）。

参数： 无

例子：

Show my recent notes

`delete_note`

按ID永久删除笔记。此操作无法撤消。

参数：

note_id （string，必填）：要删除的笔记的唯一ID

例子：

Delete note with ID "abc-123-def-456"

______________________________________________________________________

API终点

公共端点（无身份验证）

GET /health -健康检查
GET /.well-known/oauth-protected-resource -动态客户端注册的OAuth元数据

受保护的端点（需要OAuth令牌）

POST /mcp -主MCP端点（JSON-RPC 2.0）

- 方法： tools/list -列出可用工具 - 方法： tools/call -执行工具

______________________________________________________________________

发展

项目结构

komcp/
├── src/
│   ├── server.ts              # Main Fastify server
│   ├── config/                # Configuration (env, logger)
│   ├── middleware/            # Auth, error handling, metrics
│   ├── routes/                # HTTP routes (health, mcp)
│   ├── mcp/                   # MCP server implementation
│   │   └── tools/            # Tool implementations
│   ├── services/              # Business logic (oauth, kura, embeddings)
│   └── types/                 # TypeScript types
├── prisma/
│   └── schema.prisma          # Database schema
├── tests/
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── docs/                      # Additional documentation
├── komcp-prd.md              # Product Requirements Document
├── architecture.md            # Architecture documentation
├── BUILD-CHECKLIST.md         # Implementation checklist
├── CLAUDE-CODE-RULES.md       # Development rules
└── README.md                  # This file

可用脚本

# Development
npm run dev          # Start dev server with hot reload
npm run build        # Build TypeScript
npm start            # Start production server

# Testing
npm test             # Run all tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage

# Code Quality
npm run lint         # Run ESLint
npm run format       # Format with Prettier
npm run typecheck    # Check TypeScript types

# Database
npx prisma generate  # Generate Prisma client
npx prisma studio    # Open database GUI

运行测试

# Run all tests
npm test

# Run specific test file
npm test -- oauth.test.ts

# Run with coverage
npm run test:coverage

______________________________________________________________________

Docker部署

构建图像

docker build -f docker/Dockerfile -t komcp:latest .

使用Docker Compose运行

cd docker
docker-compose up -d

查看日志

docker-compose logs -f komcp

停止服务

docker-compose down

______________________________________________________________________

生产部署

看建筑检查表.md 完整部署指南的第10阶段。

快速生产检查表

\[\]所有测试均通过
\[\]已配置环境变量
\[\]已安装SSL证书
\[\]数据库只读用户已创建
\[\]KOauth支持动态客户端注册
\[\]已配置健康检查
\[\]监控/警报设置
\[\]记录备份计划

______________________________________________________________________

配置

环境变量

看 .env.example 对于所有可用的配置选项。

必修的：

KOAUTH_URL -KOauth OAuth2服务器URL
KOAUTH_JWKS_URL -用于令牌验证的JWKS端点
KURA_URL -库拉API基础URL
BASE_URL -此服务器的公共URL

可选：

PORT -服务器端口（默认：3003）
LOG_LEVEL -日志级别：调试、信息、警告、错误（默认值：信息）
RATE_LIMIT_MAX -每个窗口的最大请求数（默认值：100）
ALLOWED_ORIGINS -CORS允许的来源（默认值：https://claude.ai)

______________________________________________________________________

安全

OAuth2流

Claude发送没有令牌的请求→ KOmcp返回401
Claude通过以下方式发现OAuth端点 /.well-known/oauth-protected-resource
Claude向KOauth动态注册（RFC 7591）
用户通过KOauth web UI授权
Claude收到访问令牌
Claude向发送MCP请求 Authorization: Bearer 头球
KOmcp通过JWKS验证令牌并检查作用域

所需范围

mcp:tools:read -列出可用工具
mcp:tools:execute -执行工具
kura:notes:read -阅读库拉笔记（搜索、获取、列表）
kura:notes:write -写库拉笔记（创建）
kura:notes:delete -删除库拉笔记

安全功能

✅ 仅限HTTPS（TLS 1.3）
✅ 对每个请求进行OAuth2令牌验证
✅ 通过JWKS验证JWT签名
✅ 范围验证
✅ 每位客户的费率限制
✅ 只读数据库访问
✅ 参数化查询（防止SQL注入）
✅ 日志中没有敏感数据
✅ 安全标头（HSTS、CSP等）

______________________________________________________________________

故障排除

服务器无法启动

检查环境变量：

npm run dev
# Look for "Environment validation failed" errors

检查数据库连接：

npx prisma db pull

OAuth令牌验证失败

检查JWKS端点是否可访问：

curl https://auth.example.com/.well-known/jwks.json

检查令牌格式：

# Token should be: Authorization: Bearer 
# Verify token is valid JWT at jwt.io

搜索未返回任何结果

检查数据库是否有注释：

SELECT COUNT(*) FROM notes WHERE user_id = 'your-user-id';

检查是否存在嵌入：

SELECT COUNT(*) FROM notes WHERE embedding IS NOT NULL;

相似性阈值下限：

// Try min_similarity: 0.5 instead of 0.7

克劳德无法连接

检查服务器是否可公开访问：

curl https://mcp.example.com/health

检查CORS配置：

ALLOWED_ORIGINS=https://claude.ai

检查OAuth元数据端点：

curl https://mcp.example.com/.well-known/oauth-protected-resource

______________________________________________________________________

文档

komcp-prd.md -产品需求文件（MVP范围、功能、成功标准）
architecture.md -技术架构和设计决策
建筑检查表.md -分阶段实施任务
CLAUDE-CODE-RULES.md -开发规则和最佳实践

外部引用

______________________________________________________________________

贡献

复刻仓库
创建要素分支： git checkout -b feat/my-feature
跟随 CLAUDE-CODE-RULES.md
为新功能编写测试
确保所有测试通过： npm test
使用常规提交格式提交： feat: add new feature
推叉并提交拉叉请求

______________________________________________________________________

路线图

第一阶段-MVP✅ 完成

✅ OAuth2令牌验证
✅ 动态客户端注册
✅ Docker部署
✅ search_kura_notes 工具

第2阶段-API全面集成✅ 完成

✅ create_note 工具
✅ get_note 工具
✅ list_recent_notes 工具
✅ delete_note 工具
✅ Kura API客户端集成

第3阶段-高级功能（计划中）

update_note 工具
通过SSE实时更新
MCP资源（将笔记作为资源公开）
MCP提示（模板查询）
高级搜索过滤器（标签、日期范围）
缓存层（Redis）

第4阶段-运营（计划）

监控仪表板
使用情况分析
多区域部署

______________________________________________________________________

许可证

MIT许可证-请参阅许可证详情

______________________________________________________________________

支持

问题：
文档： 看 docs/ 目录
电子邮件： \[您的支持电子邮件\]

______________________________________________________________________

致谢

Anthropic 对于MCP规范
KOauth 对于OAuth2基础架构
Kura指出语义搜索功能的应用

______________________________________________________________________

状态： ✅ 第2阶段完成-API全面集成

最后更新时间： 2025-12-04

K Omcp

快速接入

详细介绍

KOmcp

概述

什么是MCP？

主要特点

建筑

组件

技术栈

先决条件

快速开始

1.克隆存储库

2.安装依赖项

3.配置环境

4.启动开发服务器

5.验证健康状况

Docker部署

生产部署

Docker开发

Docker环境

构建VPS部署

用法

将KOmcp添加到Claude

在Claude中使用

可用工具

search_kura_notes

create_note

get_note

list_recent_notes

delete_note

API终点

公共端点（无身份验证）

受保护的端点（需要OAuth令牌）

发展

项目结构

可用脚本

运行测试

Docker部署

构建图像

使用Docker Compose运行

查看日志

停止服务

生产部署

快速生产检查表

配置

环境变量

安全

OAuth2流

所需范围

安全功能

故障排除

服务器无法启动

OAuth令牌验证失败

搜索未返回任何结果

克劳德无法连接

文档

外部引用

贡献

路线图

第一阶段-MVP✅ 完成

第2阶段-API全面集成✅ 完成

第3阶段-高级功能（计划中）

第4阶段-运营（计划）

许可证

支持

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`search_kura_notes`

`create_note`

`get_note`

`list_recent_notes`

`delete_note`