<!--
---
title: Arabica v0.0.3 MCP Inspector 测试指南
description: 指导开发人员使用官方 MCP Inspector 工具对 Project Caffeine v0.0.3 版本的核心原语（Tools、Resources）进行标准化的交互联调与测试。
type: Test Guide
version: v0.0.3 (Arabica)
file: arabica-v0.0.3-mcp-inspector-test-guide.md
author: Gitconomy Research-郭晧
date: 2026-03-10
tags:
  - Project Caffeine
  - MCP
  - MCP Inspector
  - 测试指南
license: CC BY-SA 4.0
status: Active
---
-->
# Project Caffeine Arabica v0.0.3 MCP Inspector 测试指南

## 1. 测试目的的概述

本文档旨在为开发人员提供一份标准化的操作指南，使用官方的 **MCP Inspector** 工具对 Project Caffeine (v0.0.3) 的底层协议接口进行独立测试。通过脱离具体的大模型客户端（如 Claude Desktop），我们可以直接验证系统暴露的 Tools（工具）与 Resources（资源）原语的逻辑正确性、参数校验机制以及边缘异常处理能力。

## 2. 测试环境的准备

### 2.1 配置系统的环境变量

在启动测试之前，必须确保本地环境中的配置项已正确挂载。请在项目根目录的 `src/.env` 文件中检查以下关键路径，确保其指向本地真实的测试用例目录：

```bash
# 必须配置为本地真实存在的目录，且具备读写权限
OBSIDIAN_VAULT_PATH=/真实的/本地/测试目录/MyVault
LITERATURE_STORAGE_PATH=/真实的/本地/测试目录/MyVault
````

## 2.2 构建并启动检查器

Project Caffeine 的服务端运行依赖于编译后的 JavaScript 代码。请在终端中依次执行以下命令，完成项目的构建并通过 `npx` 启动官方的 MCP Inspector：

Bash

```bash
# 1. 编译 TypeScript 源码
npm run build

# 2. 启动 MCP Inspector 并挂载编译后的入口文件
npx @modelcontextprotocol/inspector node dist/app.js
```

启动成功后，终端将输出一个本地调试地址（通常为 `http://localhost:5173`）。请在浏览器中打开该地址，进入 MCP Inspector 的可视化调试界面。

## 3. 核心原语的测试流程

在 MCP Inspector 的 Web 界面中，您将看到系统成功连接的标识 `Project-Caffeine-Arabica-Intent-Mode (v0.0.3)`。接下来，请依次对以下核心功能模块进行拨测。

## 3.1 执行文献检索工具测试 (Tools)

系统通过 `search_arxiv` 工具提供外部学术数据的抓取能力。

1. **定位工具**：在左侧面板选择 **Tools** 选项卡，在列表中找到并选中 `search_arxiv`。

2. **输入参数**：在参数输入框中填入合法的 JSON 负载：

    JSON

    ```bash
    {
      "query": "Large Language Models in Healthcare"
    }
    ```

3. **发起调用**：点击 **Run Tool** 按钮。

4. **验证结果**：

    - **预期成功**：右侧响应区应返回状态 `isError: false`，且 `content` 数组中包含格式化好的文献标题、链接与摘要列表。

    - **预期异常**：若输入空的 `query`，系统应触发 Zod 校验拦截，提示“需要检索的学术核心关键字”。


## 3.2 执行思维框架获取测试 (Tools)

系统将静态思维模板通过 `fetch_framework_template` 工具暴露给大模型。

1. **定位工具**：在 Tools 列表中选中 `fetch_framework_template`。

2. **输入参数**：

    JSON

    ```bash
    {
      "framework_name": "scqa"
    }
    ```

3. **发起调用**：点击 **Run Tool** 按钮。

4. **验证结果**：

    - **预期成功**：响应文本中应包含“【🛑 最高优先级的底层执行指令 🛑】”以及 SCQA 框架的系统设定与结构要求。

    - **边缘测试**：尝试输入未注册的框架（如 `abcd`），系统应返回软拦截提示：“未找到框架 abcd。系统支持的框架有: swot, scqa, pestle, 5w3h, 5whys”。


## 3.3 执行双轨制落盘与读取测试 (Tools)

验证系统对本地文件系统的 I/O 控制与路径安全防范。

1. **保存笔记测试 (`save_note`)**：

    - 构造参数：`{ "filename": "inspector_test.md", "content": "## 测试数据\n这是由 Inspector 写入的测试内容。" }`

    - 执行后，检查本地 `OBSIDIAN_VAULT_PATH` 目录下是否成功生成了 `inspector_test.md` 文件。

2. **防穿越安全红线测试 (`save_note`)**：

    - 构造参数：`{ "filename": "../hacked.md", "content": "危险载荷" }`

    - **验证预期**：系统必须返回 `isError: true`，并明确提示“无效的文件名，不允许访问上层目录”。

3. **列出笔记测试 (`list_local_notes`)**：

    - 直接运行该工具（无需参数）。系统应返回刚才创建的 `inspector_test.md`。

4. **读取笔记测试 (`read_local_note`)**：

    - 构造参数：`{ "filename": "inspector_test.md" }`。

    - 系统应正确返回刚写入的 Markdown 文本内容。


## 3.4 验证本地静态资源挂载 (Resources)

Resources 原语用于将本地知识库作为被动只读资源暴露，以便大模型在对话上下文中作为附件引用。

1. **获取资源列表**：

    - 在左侧面板切换至 **Resources** 选项卡。

    - 点击 **List Resources**，系统应返回由 `note://local/` 协议开头的资源列表，且列表中应包含 `note://local/inspector_test.md`。

2. **读取特定资源**：

    - 选中 `note://local/inspector_test.md`。

    - 点击 **Read Resource** 按钮。

    - **验证结果**：响应区应成功解码 URI 参数，并返回该文件的原始内容文本。


## 4. 常见问题与排错方案

## 4.1 解决连接超时的异常

如果 MCP Inspector 在启动后长时间处于 `Connecting...` 状态，请排查以下可能：

- **检查编译产物**：确认 `npm run build` 是否成功执行，`dist/app.js` 文件是否存在。

- **检查端口占用**：MCP Inspector 默认使用 `5173` 端口，若端口被占用，可通过环境变量更换端口。


## 4.2 解决本地路径挂载失败的异常

当调用 `save_note` 抛出文件写入失败时：

- **检查环境配置**：确认 `.env` 文件中的 `OBSIDIAN_VAULT_PATH` 路径是否拼写正确，且必须为绝对路径。

- **检查目录权限**：确保当前运行 Node.js 进程的用户对该绝对路径具有完全读写权限。


---

## 许可声明

本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research。
