filevine-mcp

Filevine MCP — Claude 集成

由 Oktopeak 构建 — 为律师事务所提供 AI 转型与自动化服务

为法律和医疗健康企业提供数字化转型服务。 我们打造由贵所完全拥有的 AI 集成、工作流自动化和定制软件——包括此连接器。→ 预约 30 分钟通话

一个开源 MCP（Model Context Protocol）服务，用于连接 Claude 与 Filevine 律所管理平台。可通过 Claude 访问案件、联系人、文档、备注、任务和自定义人身伤害数据，并具备自动速率限制和审计日志功能。

支持的端点： 15 个工具，涵盖 Filevine v2 REST API。

提示

不是开发者？也不需要是。

以下 README 假设读者熟悉如何编辑 JSON 配置文件。如果您或您的团队不熟悉，我们可以为律师事务所部署此服务：配置限定范围的凭据、接入审计日志、设置一个自定义工作流并提供培训。

→ 整家律所？律所计划：每月 $300。 在您自己的云端部署，每位律师使用自己的账号登录，共用一份审计日志，每月为您构建一项自动化，无设置费用，可随时取消。→ oktopeak.com/firm-plan/，或预约 30 分钟通话

跳转至： 设置 · 可用工具 · 合规与安全 · 需要我们为您部署？ · 其他连接器

---

设置

1. 前置条件

• Node.js 18+
• 已启用 API 访问权限的 Filevine 账号
• 从贵所的 Filevine 设置中获取的 Client ID、Client Secret 和 Personal Access Token（PAT）
• Claude Code、MCP 客户端或兼容应用程序

2. 获取 Filevine 凭据

1. Personal Access Token（PAT）

   • 前往 Filevine Settings → Access Tokens → Generate PAT
   • 复制并妥善保存

2. 客户端凭据

   • 前往 Settings → Client Secrets → Create Client ID + Client Secret
   • 有效期为 1 年，可随时轮换
   • 复制这两个值

3. 组织和用户 ID（首次身份验证时自动发现）

   • 服务将在首次运行时从 /v2/users/me 获取这些信息

3. 环境变量

将 .env.example 复制为 .env：

# Filevine OAuth client credentials
FILEVINE_CLIENT_ID=<from Settings → Client Secrets>
FILEVINE_CLIENT_SECRET=<from Settings → Client Secrets>
FILEVINE_PAT=<from Settings → Access Tokens>

# API region (us or ca)
FILEVINE_REGION=us

# Token encryption key (generate new one)
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=<64-character-hex-string>

4. 安装并构建

npm install
npm run build

5. 运行服务

# Start the server
npm start

# Or use MCP inspector for debugging
npm run inspect

服务通过 stdio 监听，并将连接状态输出到 stderr。

6. 身份验证

使用任何 Filevine 工具之前，请调用 authenticate 工具：

Tool: authenticate
→ Exchanges PAT for access token
→ Discovers org_id and user_id
→ Stores encrypted tokens in ~/.oktopeak-filevine/tokens.enc

令牌会在过期前自动刷新（TTL 为 3600s）。调用 logout 可清除已存储的令牌。

---

工具（共 15 个）

身份验证（3 个工具）

工具	用途
authenticate	使用 PAT 换取访问令牌，并缓存组织/用户 ID
auth-status	检查身份验证状态和令牌过期时间
logout	清除已存储的令牌

案件 — 项目（2 个工具）

工具	用途
list-cases	列出案件（活跃、已结案、待处理）；按名称/编号搜索
get-case	根据 ID 获取完整的案件详情

联系人（3 个工具）

工具	用途
search-contacts	在所有案件中按姓名、电子邮件或电话号码搜索联系人
get-contact	根据 ID 获取联系人详情
list-case-contacts	列出特定案件中的所有联系人

备注（2 个工具）

工具	用途
list-notes	列出案件备注；支持 general、phone_call 和 internal 类型
create-note	创建备注（例如 AI 摘要、调查结果、后续跟进）

文档（1 个工具）

工具	用途
list-documents	列出案件文档及其元数据（名称、类型、大小、URL、日期）

注意： 仅返回文档元数据，不包含二进制内容。如需获取文档内容，请使用返回的 URL。

任务（2 个工具）

工具	用途
list-tasks	按状态（未完成、已完成、逾期）列出案件任务
create-task	创建新任务，并设置标题、描述、受派人和截止日期

已知问题： 截至 2025 年 8 月，Filevine API 可能会忽略 targetDate 字段。解决方法：通过 UI 设置任务。

自定义数据 — 集合（2 个工具）

工具	用途
discover-schema	映射律所的自定义部分（医疗记录、留置权、和解等）
get-collection	使用发现的选择器获取自定义集合数据

集合为何重要： 与标准化案件字段不同，每家律所都会为 PI 工作流构建自定义的“Collection sections”。discover-schema 工具可查找律所的结构。

示例工作流：

1. 调用 discover-schema → 查看可用部分（例如“MedicalRecords”“Liens”）
2. 使用发现结果中的选择器 → 调用 get-collection 获取 PI 专属数据

---

速率限制与性能

Filevine 速率限制：

端点	限制
标准	320 次请求/端点/分钟
计费	250 次请求/端点/分钟
报告/Vitals	5 次请求/端点/分钟
VineSign	10 次请求/用户/月

实现方式：

• 使用每分钟 300 次请求的令牌桶（较为保守）
• 对 429 Too Many Requests 进行指数退避（1 秒 → 2 秒 → 4 秒 → … → 最长 30 秒）
• 在触及速率限制前自动等待

---

API 详情

请求流程

1. 令牌交换（首次调用 authenticate 时）

   POST https://identity.filevine.com/connect/token
   client_id, client_secret, grant_type=personal_access_token, token=PAT
   → access_token (3600s), refresh_token, scopes
   

2. 组织/用户发现

   GET /v2/users/me
   Authorization: Bearer {access_token}
   → {id: user_id, org_id: org_id}
   

3. 每个 API 请求（需要 3 个请求头）

   Authorization: Bearer {access_token}
   x-fv-orgid: {org_id}
   x-fv-userid: {user_id}
   

基础 URL

• US： https://api.filevine.io
• CA： https://api.filevine.ca

通过 FILEVINE_REGION 环境变量设置。

身份验证请求头

与其他法律 API 最大的区别是：每个请求都需要 3 个请求头，而不仅仅是 Authorization。Filevine 使用 x-fv-orgid 和 x-fv-userid，将查询限定在正确的组织和用户上下文中。

---

架构

src/
├── index.ts                      # Server entry point
├── filevine-client.ts            # API client with 3-header middleware
├── auth/
│   ├── authTools.ts              # authenticate, auth-status, logout
│   ├── oauth.ts                  # PAT token exchange + org/user discovery
│   └── token-store.ts            # AES-256-GCM encrypted token storage
├── tools/
│   ├── cases.ts                  # list-cases, get-case
│   ├── contacts.ts               # search-contacts, get-contact, list-case-contacts
│   ├── notes.ts                  # list-notes, create-note
│   ├── documents.ts              # list-documents
│   ├── tasks.ts                  # list-tasks, create-task
│   └── collections.ts            # discover-schema, get-collection
├── resources/
│   ├── auth-status.ts            # Auth status resource (filevine://auth/status)
│   └── compliance.ts             # Compliance notice
├── audit/
│   └── logger.ts                 # Audit logging (JSON-lines)
└── utils/
    └── rate-limiter.ts           # Token bucket + 429 backoff

令牌存储

令牌使用 AES-256-GCM 加密，并存储在本地：

• 位置： ~/.oktopeak-filevine/tokens.enc
• 加密： 使用随机 IV 和身份验证标签的 AES-256-GCM
• 密钥： .env 中的 ENCRYPTION_KEY（64 位十六进制）

审计日志记录

每次工具调用都会记录到 ~/.oktopeak-filevine/audit.log：

• 时间戳、工具名称、参数（已删除机密信息）
• 结果（成功/错误）、用户 ID、案件 ID、结果数量
• 支持用于 ABA Opinion 512 合规性文档记录

---

错误处理

常见错误

错误	原因	修复方法
ENCRYPTION_KEY is not set	缺少环境变量	生成密钥：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
PAT exchange failed (401)	凭据无效	在 Filevine Settings 中验证 Client ID、Secret 和 PAT
Failed to discover user info	令牌不具备所需权限范围	在 Filevine 中重新生成 PAT 和 Client Credentials
429 Too Many Requests	触及速率限制	服务会自动退避；负载较高时属于正常行为
Unknown collection selector	未找到选择器	运行 discover-schema 查找可用选择器

---

开发

TypeScript

• 已启用严格模式
• ES2022 目标版本，Node16 模块
• npm run build → build/ 目录

依赖项

• @modelcontextprotocol/sdk — MCP 协议
• dotenv — 环境变量加载
• zod — 工具参数的模式验证
• crypto、fs、http — Node 内置模块

调试

npm run inspect

在 http://localhost:3000 打开 MCP 检查器 — 测试工具、检查参数并验证响应。

测试

npm run build
npm start
# In another terminal:
npm run inspect

---

资源

Filevine 官方资源

• API 文档： developer.filevine.io
• 支持： support.filevine.com/hc/en-us
• 示例： github.com/Filevine/filevine-api-examples（C#、JS、Python）
• 速率限制： support.filevine.com/hc/en-us/articles/30948396130203

参考实现

• Treillage（Python）： github.com/W1ndst0rm/Treillage — 速率限制器和令牌刷新参考实现

---

合规与安全

• 数据处理： 按需获取所有 Filevine 数据，不在本地缓存任何数据
• 令牌存储： 在磁盘上使用 AES-256-GCM 加密；解密需要 ENCRYPTION_KEY
• 审计日志： 记录每次工具调用，并对机密信息进行脱敏
• 速率限制： 每分钟滚动窗口限制为 300 次请求，并通过 429 退避机制保护你的账户
• 写入权限： 只有 create-note 和 create-task 会修改数据
• 令牌刷新： 在令牌过期前 5 分钟自动刷新（TTL 为 3600s）

请参阅 src/resources/compliance.ts 了解完整的合规声明。

---

许可证

MIT — Oktopeak

---

需要的不只是连接器？

这个开源连接器会读取你的 Filevine 数据，并让 Claude 使用这些数据。这能满足大多数律所最终需求的大约 20%。

我们会根据你的需求范围，通过两种方式提供帮助：

→ 整个律所？Firm Plan：每月 300 美元。 部署在你自己的云端，每位律师使用自己的登录账号，每月为你构建一个自动化流程，集中管理一份审计日志，无设置费，随时可取消。→ oktopeak.com/firm-plan/

→ Filevine 集成：适用于自定义报告、项目架构设计、文档和受理流程自动化，以及围绕 Filevine 构建的生产级软件层。 → oktopeak.com/services/filevine-integration/

想查看这款连接器的精美介绍和常见问题解答？ → oktopeak.com/filevine-mcp/

想先聊聊？→ 预约 30 分钟需求沟通

---

Oktopeak 的其他连接器

我们也为其他律所管理平台提供同类连接器。每款产品都在 oktopeak.com 上设有独立的介绍页面：

• Clio MCP：Clio 律所管理平台。源码：github.com/oktopeak/clio-mcp。npm：@oktopeak/clio-mcp
• MyCase MCP：MyCase 法律业务管理平台。源码：github.com/oktopeak/mycase-mcp。npm：@oktopeak/mycase-mcp
• Lawmatics MCP：Lawmatics 法律 CRM 和客户受理流程。源码：github.com/oktopeak/lawmatics-mcp。npm：@oktopeak/lawmatics-mcp
• IntakeQ / PracticeQ MCP：适用于 IntakeQ/PracticeQ（医疗保健）的 HIPAA 合规连接器。每次读取或写入 PHI 时都会记录审计日志。npm：@oktopeak/intakeq-mcp

采用相同的架构、审计日志机制和静态加密方式。全部采用 MIT 许可证。

---

支持此项目

此连接器免费提供，采用 MIT 许可，并由 Oktopeak 维护。它将始终如此——我们不接受捐赠。如果它为你节省了时间，以下方式确实能帮上忙：

• 为此仓库点星。 其他律所确实是通过这种方式找到它的。
• 告诉另一家 使用 Filevine 的律所。
• 如果我们直接帮到了你，留下评价。
• 需要为你的律所部署、扩展或维护它？商业支持——这正是为免费工作提供资金的方式。

关于我们

Oktopeak — 为律所和医疗保健行业提供数字化转型服务。

我们是一支由 7 人组成的内部产品团队，为受监管行业打造 AI 解决方案：AI 集成、工作流自动化，以及由客户完全拥有的定制软件。我们维护五个开源 MCP 连接器——Clio、MyCase、Filevine、Lawmatics 和 IntakeQ——并将它们部署在真实的业务环境中，使用权限范围明确的凭据、审计日志，以及围绕团队实际工作方式构建的工作流。

• 🌐 oktopeak.com
• 📅 预约 30 分钟通话
• ✉️ [email protected] — 欢迎提交安全问题报告
• 💼 LinkedIn