项目简介

'tracker' 是一个多组件项目，其中包含一个用于跟踪用户位置的移动应用，以及一个将这些位置信息以标准化方式暴露给AI的MCP服务器。MCP服务器通过JSON-RPC协议提供数据访问和功能调用，支持AI客户端获取实时的或历史的位置上下文，从而赋能各种智能应用，如个人助理、行为分析等。

主要功能点

位置数据托管: MCP服务器存储由移动应用上传的用户地理位置数据，包括时间戳、坐标、精度和来源等信息。
资源访问能力: 允许AI客户端通过统一资源标识符 (URI) 访问特定的位置记录作为资源。例如，AI可以请求 'location://<id>' 来获取某个位置的详细信息。
工具调用能力:
- 'get_locations': AI客户端可以调用此工具，根据日期范围（开始日期、结束日期）和返回数量限制，查询用户的历史位置数据列表。
- 'get_location_stats': AI客户端可以调用此工具，获取指定天数内（例如最近30天）的位置数据统计信息，包括总位置数量、活跃天数、平均每日位置数量以及按数据来源（如后台、手动按钮）分类的统计。
JSON-RPC协议通信: 服务器通过标准的JSON-RPC 2.0协议接收和响应AI客户端的请求，确保跨平台和语言的互操作性。
认证与授权: 服务器支持基于密钥的认证机制（通过 'X-Tracker-Secret' 请求头），保护用户数据安全。

安装步骤

环境准备:
- 确保您的系统已安装 Node.js (推荐LTS版本) 和 pnpm 包管理器。
- 准备一个PostgreSQL数据库实例。您可以使用本地安装的PostgreSQL，也可以使用云服务（如Neon、Supabase等）。

克隆仓库:

git clone https://github.com/felipap/tracker.git
cd tracker

进入Web目录:
```
cd web
```
安装依赖:
```
pnpm install
```
配置环境变量:
- 在 'web/' 目录下创建一个 '.env.local' 文件（或 '.env'），并配置以下变量：
  - 'DATABASE_URL': 您的PostgreSQL数据库连接字符串。例如：'postgresql://user:password@host:port/database'
  - 'MOBILE_REQUEST_SECRET': 一个安全的密钥字符串，用于API认证。请生成一个强密码。例如：'my_super_secret_api_key_123'
  - 'WEBSITE_SECRET': (可选) 用于Web界面登录的密码，与MCP服务器无关。
数据库迁移:
- 运行数据库迁移以创建必要的表结构。通常，您会使用 Drizzle Kit 进行迁移。例如：
```
pnpm drizzle-kit push:pg
```
启动服务器:
```
pnpm dev
```
服务器将在 'http://localhost:3000' 启动，MCP API 端点为 'http://localhost:3000/api/mcp'。

服务器配置 (面向MCP客户端)

您的MCP客户端需要以下JSON格式的配置信息，以便能够连接和使用此MCP服务器：

{
  "name": "location-tracker",
  "command": ["<Your_HTTP_Client_Executable_or_Script>", "<Args_for_HTTP_Request>"],
  "args": [],
  "description": "提供用户位置信息和相关统计分析的MCP服务器。",
  "connection_details": {
    "url": "http://localhost:3000/api/mcp",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "X-Tracker-Secret": "YOUR_MOBILE_REQUEST_SECRET"
    }
  }
}

name: 服务器的名称，此处为 'location-tracker'。
command: 此字段通常用于启动本地服务器进程或指定通信协议的客户端执行器。由于这是一个Web API服务器，此处应替换为您的MCP客户端用于发送HTTP POST请求到服务器的实际可执行文件或脚本路径。例如，如果您的客户端使用 'curl'，这里可以是 '["curl", "-X", "POST", "-H", "Content-Type: application/json", "-H", "X-Tracker-Secret: YOUR_MOBILE_REQUEST_SECRET", "--data", "@-", "http://localhost:3000/api/mcp"]'。
args: 命令行参数，当前无额外参数。
description: 服务器功能的简要说明。
connection_details: 这是一个额外的字段，用于更清晰地说明MCP客户端连接此HTTP服务器所需的具体信息（非MCP标准字段，但对用户理解有用）。
- url: MCP服务器的API端点。如果您的服务器部署在其他地址或端口，请将 'http://localhost:3000' 替换为实际的URL。
- method: 客户端应使用HTTP POST方法发送JSON-RPC请求。
- headers: 必要的HTTP头部信息。
  - 'Content-Type: application/json': 指定请求体为JSON格式。
  - 'X-Tracker-Secret: YOUR_MOBILE_REQUEST_SECRET': 认证头部。请将 'YOUR_MOBILE_REQUEST_SECRET' 替换为您在 '.env.local' 文件中配置的 'MOBILE_REQUEST_SECRET' 密钥。

基本使用方法

AI客户端与MCP服务器的交互通过发送JSON-RPC请求实现。以下是一些基本操作示例：

初始化MCP服务器: AI客户端发送一个 'initialize' 请求，获取服务器支持的协议版本和能力。 '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}'
列出可用位置资源: AI客户端发送 'resources/list' 请求，获取所有可用位置资源的URI列表。 '{"jsonrpc": "2.0", "id": 2, "method": "resources/list", "params": {}}'
读取特定位置资源: 根据 'resources/list' 返回的URI，AI客户端可以选择一个URI（例如 'location://some_location_id'），发送 'resources/read' 请求获取该位置的详细JSON数据。 '{"jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": {"uri": "location://some_location_id"}}'
列出所有可用工具: AI客户端发送 'tools/list' 请求，获取服务器提供的所有工具列表及其输入参数Schema。 '{"jsonrpc": "2.0", "id": 4, "method": "tools/list", "params": {}}'
调用 'get_locations' 工具: AI客户端调用 'get_locations' 工具，查询2023年1月1日至2023年1月31日之间的最多10个位置记录。 '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "get_locations", "arguments": {"startDate": "2023-01-01T00:00:00Z", "endDate": "2023-01-31T23:59:59Z", "limit": 10}}}'
调用 'get_location_stats' 工具: AI客户端调用 'get_location_stats' 工具，获取最近7天的位置统计数据。 '{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "get_location_stats", "arguments": {"days": 7}}}'

关键词

项目简介

主要功能点

安装步骤

服务器配置 (面向MCP客户端)

基本使用方法

信息