Spaces:
Running
Running
| { | |
| "$schema": "https://json-schema.org/draft-07/schema#", | |
| "title": "MCP Tools for Obsidian-Like Docs Viewer", | |
| "description": "FastMCP tool definitions for multi-tenant documentation viewer with JSON Schema validation (Pydantic)", | |
| "tools": [ | |
| { | |
| "name": "list_notes", | |
| "title": "List Notes", | |
| "description": "List all notes in the authenticated user's vault with optional folder filtering. Returns lightweight summaries with path, title, and last modified timestamp.", | |
| "inputSchema": { | |
| "type": "object", | |
| "properties": { | |
| "folder": { | |
| "type": "string", | |
| "description": "Optional folder path to filter notes (e.g., 'api' or 'guides/tutorials'). If omitted, returns all notes in the vault.", | |
| "maxLength": 256, | |
| "examples": ["api", "guides/tutorials", ""] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "array", | |
| "description": "Array of note summaries, sorted by most recently updated first", | |
| "items": { | |
| "type": "object", | |
| "required": ["path", "title", "last_modified"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Relative path to vault root (includes .md extension)", | |
| "examples": ["api/design.md", "README.md"] | |
| }, | |
| "title": { | |
| "type": "string", | |
| "description": "Display title (from frontmatter, H1, or filename)", | |
| "examples": ["API Design", "README"] | |
| }, | |
| "last_modified": { | |
| "type": "string", | |
| "format": "date-time", | |
| "description": "Last modification timestamp (ISO 8601)", | |
| "examples": ["2025-01-15T14:30:00Z"] | |
| } | |
| } | |
| }, | |
| "examples": [ | |
| [ | |
| { | |
| "path": "api/design.md", | |
| "title": "API Design", | |
| "last_modified": "2025-01-15T14:30:00Z" | |
| }, | |
| { | |
| "path": "api/endpoints.md", | |
| "title": "API Endpoints", | |
| "last_modified": "2025-01-14T09:15:00Z" | |
| } | |
| ] | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "read_note", | |
| "title": "Read Note", | |
| "description": "Retrieve full note content including metadata (frontmatter), body (markdown), and system-managed fields (version, timestamps). Use this to access existing documentation.", | |
| "inputSchema": { | |
| "type": "object", | |
| "required": ["path"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Relative path to vault root (includes .md extension, e.g., 'api/design.md')", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "pattern": "^[^/].*\\.md$", | |
| "examples": ["api/design.md", "README.md", "guides/setup.md"] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "object", | |
| "required": ["path", "title", "metadata", "body"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Note path (echo of input)", | |
| "examples": ["api/design.md"] | |
| }, | |
| "title": { | |
| "type": "string", | |
| "description": "Display title", | |
| "examples": ["API Design"] | |
| }, | |
| "metadata": { | |
| "type": "object", | |
| "description": "Frontmatter key-value pairs (arbitrary structure)", | |
| "properties": { | |
| "tags": { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| } | |
| }, | |
| "project": { | |
| "type": "string" | |
| }, | |
| "created": { | |
| "type": "string", | |
| "format": "date-time" | |
| }, | |
| "updated": { | |
| "type": "string", | |
| "format": "date-time" | |
| } | |
| }, | |
| "additionalProperties": true, | |
| "examples": [ | |
| { | |
| "tags": ["backend", "api"], | |
| "project": "auth-service" | |
| } | |
| ] | |
| }, | |
| "body": { | |
| "type": "string", | |
| "description": "Markdown content (excluding frontmatter YAML)", | |
| "examples": ["# API Design\n\nThis document describes the API architecture...\n\n## Endpoints\n\nSee [[Endpoints]] for details."] | |
| } | |
| }, | |
| "examples": [ | |
| { | |
| "path": "api/design.md", | |
| "title": "API Design", | |
| "metadata": { | |
| "tags": ["backend", "api"], | |
| "project": "auth-service" | |
| }, | |
| "body": "# API Design\n\nThis document describes the API architecture..." | |
| } | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "write_note", | |
| "title": "Write Note", | |
| "description": "Create a new note or update an existing note. Automatically manages version, created/updated timestamps, and index updates. Uses last-write-wins strategy (no version conflict detection for MCP writes).", | |
| "inputSchema": { | |
| "type": "object", | |
| "required": ["path", "body"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Relative path to vault root (includes .md extension). Must not contain '..', use Unix separators (/), and be relative (no leading /).", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "pattern": "^[^/].*\\.md$", | |
| "examples": ["api/design.md", "README.md", "guides/new-feature.md"] | |
| }, | |
| "title": { | |
| "type": "string", | |
| "description": "Optional title override (if omitted, will be extracted from frontmatter or first H1 heading in body)", | |
| "examples": ["API Design", "New Feature Guide"] | |
| }, | |
| "metadata": { | |
| "type": "object", | |
| "description": "Optional frontmatter metadata (arbitrary key-value pairs). Common fields: tags (array), project (string), etc.", | |
| "properties": { | |
| "tags": { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| }, | |
| "description": "Tag names for categorization" | |
| }, | |
| "project": { | |
| "type": "string", | |
| "description": "Project identifier" | |
| } | |
| }, | |
| "additionalProperties": true, | |
| "examples": [ | |
| { | |
| "tags": ["backend", "api"], | |
| "project": "auth-service" | |
| } | |
| ] | |
| }, | |
| "body": { | |
| "type": "string", | |
| "description": "Markdown content (max 1 MiB UTF-8). Can contain wikilinks using [[link text]] syntax.", | |
| "maxLength": 1048576, | |
| "examples": ["# API Design\n\nThis document describes the API architecture...\n\n## Related\n\nSee [[Endpoints]] for endpoint details."] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "object", | |
| "required": ["status", "path"], | |
| "properties": { | |
| "status": { | |
| "type": "string", | |
| "enum": ["ok"], | |
| "description": "Operation status" | |
| }, | |
| "path": { | |
| "type": "string", | |
| "description": "Path of the created/updated note", | |
| "examples": ["api/design.md"] | |
| } | |
| }, | |
| "examples": [ | |
| { | |
| "status": "ok", | |
| "path": "api/design.md" | |
| } | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "delete_note", | |
| "title": "Delete Note", | |
| "description": "Permanently delete a note from the vault and remove it from all indices (full-text, tags, links). Any wikilinks referencing this note will become unresolved.", | |
| "inputSchema": { | |
| "type": "object", | |
| "required": ["path"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Relative path to vault root (includes .md extension)", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "pattern": "^[^/].*\\.md$", | |
| "examples": ["api/design.md", "obsolete/old-doc.md"] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "object", | |
| "required": ["status"], | |
| "properties": { | |
| "status": { | |
| "type": "string", | |
| "enum": ["ok"], | |
| "description": "Operation status" | |
| } | |
| }, | |
| "examples": [ | |
| { | |
| "status": "ok" | |
| } | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "search_notes", | |
| "title": "Search Notes", | |
| "description": "Full-text search across all notes in the user's vault. Results are ranked using: (3 * title_matches) + (1 * body_matches) + recency_bonus. Returns snippets with highlighted matches.", | |
| "inputSchema": { | |
| "type": "object", | |
| "required": ["query"], | |
| "properties": { | |
| "query": { | |
| "type": "string", | |
| "description": "Search query (tokenized, case-insensitive). Supports simple keyword search with automatic stemming (e.g., 'running' matches 'run').", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "examples": ["authentication", "API design", "database schema"] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "array", | |
| "description": "Search results sorted by relevance score (descending). Limited to top 50 results.", | |
| "maxItems": 50, | |
| "items": { | |
| "type": "object", | |
| "required": ["path", "title", "snippet"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Note path", | |
| "examples": ["api/auth.md"] | |
| }, | |
| "title": { | |
| "type": "string", | |
| "description": "Note title", | |
| "examples": ["Authentication Flow"] | |
| }, | |
| "snippet": { | |
| "type": "string", | |
| "description": "Highlighted excerpt from body (max ~200 chars, with <mark> tags around matches)", | |
| "examples": ["...describes the <mark>authentication</mark> process using JWT tokens..."] | |
| } | |
| } | |
| }, | |
| "examples": [ | |
| [ | |
| { | |
| "path": "api/auth.md", | |
| "title": "Authentication Flow", | |
| "snippet": "...describes the <mark>authentication</mark> process using JWT tokens..." | |
| }, | |
| { | |
| "path": "guides/setup.md", | |
| "title": "Setup Guide", | |
| "snippet": "...configure <mark>authentication</mark> settings in the config file..." | |
| } | |
| ] | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "get_backlinks", | |
| "title": "Get Backlinks", | |
| "description": "Get all notes that reference the specified note via wikilinks (e.g., [[Note Name]]). Useful for discovering related documentation and navigation.", | |
| "inputSchema": { | |
| "type": "object", | |
| "required": ["path"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Relative path to vault root (includes .md extension)", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "pattern": "^[^/].*\\.md$", | |
| "examples": ["api/design.md", "README.md"] | |
| } | |
| }, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "array", | |
| "description": "Array of notes that link to the target note, sorted by most recently updated first", | |
| "items": { | |
| "type": "object", | |
| "required": ["path", "title"], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Path of the linking note", | |
| "examples": ["guides/architecture.md"] | |
| }, | |
| "title": { | |
| "type": "string", | |
| "description": "Title of the linking note", | |
| "examples": ["Architecture Overview"] | |
| } | |
| } | |
| }, | |
| "examples": [ | |
| [ | |
| { | |
| "path": "guides/architecture.md", | |
| "title": "Architecture Overview" | |
| }, | |
| { | |
| "path": "api/endpoints.md", | |
| "title": "API Endpoints" | |
| } | |
| ] | |
| ] | |
| } | |
| }, | |
| { | |
| "name": "get_tags", | |
| "title": "Get Tags", | |
| "description": "List all tags used across the user's vault with note counts. Tags are extracted from frontmatter 'tags' field and normalized (lowercase).", | |
| "inputSchema": { | |
| "type": "object", | |
| "properties": {}, | |
| "additionalProperties": false | |
| }, | |
| "outputSchema": { | |
| "type": "array", | |
| "description": "Array of tags sorted by count (descending)", | |
| "items": { | |
| "type": "object", | |
| "required": ["tag", "count"], | |
| "properties": { | |
| "tag": { | |
| "type": "string", | |
| "description": "Tag name (lowercase, normalized)", | |
| "examples": ["backend", "api", "frontend"] | |
| }, | |
| "count": { | |
| "type": "integer", | |
| "minimum": 0, | |
| "description": "Number of notes with this tag", | |
| "examples": [15, 12, 8] | |
| } | |
| } | |
| }, | |
| "examples": [ | |
| [ | |
| { | |
| "tag": "backend", | |
| "count": 15 | |
| }, | |
| { | |
| "tag": "api", | |
| "count": 12 | |
| }, | |
| { | |
| "tag": "frontend", | |
| "count": 8 | |
| } | |
| ] | |
| ] | |
| } | |
| } | |
| ], | |
| "authentication": { | |
| "type": "bearer", | |
| "description": "MCP HTTP transport requires Bearer JWT token via 'auth' parameter. STDIO transport (local mode) does not require authentication.", | |
| "tokenSource": "POST /api/tokens", | |
| "tokenExpiration": "90 days" | |
| }, | |
| "errors": { | |
| "description": "All MCP tools follow FastMCP error handling conventions. Common error scenarios:", | |
| "errorCodes": [ | |
| { | |
| "code": "AUTHENTICATION_REQUIRED", | |
| "description": "Missing or invalid JWT token (HTTP transport only)", | |
| "httpStatus": 401 | |
| }, | |
| { | |
| "code": "PERMISSION_DENIED", | |
| "description": "Vault note limit exceeded (5,000 notes) or path traversal attempt", | |
| "httpStatus": 403 | |
| }, | |
| { | |
| "code": "NOT_FOUND", | |
| "description": "Note path does not exist in vault", | |
| "httpStatus": 404 | |
| }, | |
| { | |
| "code": "VALIDATION_ERROR", | |
| "description": "Invalid input parameters (e.g., path format, content size)", | |
| "httpStatus": 400, | |
| "details": { | |
| "invalidPath": "Path must end with .md, not contain '..' or '\\', and be relative", | |
| "payloadTooLarge": "Note body exceeds 1 MiB UTF-8 text limit", | |
| "emptyQuery": "Search query must be at least 1 character" | |
| } | |
| }, | |
| { | |
| "code": "INTERNAL_ERROR", | |
| "description": "Unexpected server error (filesystem, database, etc.)", | |
| "httpStatus": 500 | |
| } | |
| ] | |
| }, | |
| "examples": { | |
| "description": "Common usage patterns for AI agents via MCP", | |
| "scenarios": [ | |
| { | |
| "name": "Create documentation structure", | |
| "description": "AI agent creates initial project documentation with organized folders", | |
| "steps": [ | |
| { | |
| "tool": "write_note", | |
| "input": { | |
| "path": "README.md", | |
| "title": "Project Overview", | |
| "metadata": { | |
| "tags": ["overview", "documentation"] | |
| }, | |
| "body": "# Project Overview\n\nWelcome to the project.\n\n## Structure\n\n- [[API Documentation]] - API design and endpoints\n- [[Guides]] - User guides and tutorials" | |
| } | |
| }, | |
| { | |
| "tool": "write_note", | |
| "input": { | |
| "path": "api/README.md", | |
| "title": "API Documentation", | |
| "metadata": { | |
| "tags": ["api", "backend"] | |
| }, | |
| "body": "# API Documentation\n\nSee:\n- [[Authentication]] for auth flows\n- [[Endpoints]] for endpoint specs" | |
| } | |
| } | |
| ] | |
| }, | |
| { | |
| "name": "Update documentation with search", | |
| "description": "AI agent searches for existing docs before updating", | |
| "steps": [ | |
| { | |
| "tool": "search_notes", | |
| "input": { | |
| "query": "authentication" | |
| }, | |
| "output": [ | |
| { | |
| "path": "api/auth.md", | |
| "title": "Authentication Flow", | |
| "snippet": "...JWT token-based authentication..." | |
| } | |
| ] | |
| }, | |
| { | |
| "tool": "read_note", | |
| "input": { | |
| "path": "api/auth.md" | |
| } | |
| }, | |
| { | |
| "tool": "write_note", | |
| "input": { | |
| "path": "api/auth.md", | |
| "body": "# Authentication Flow\n\n[Updated content with new OAuth section...]" | |
| } | |
| } | |
| ] | |
| }, | |
| { | |
| "name": "Discover related documentation", | |
| "description": "AI agent uses backlinks to find related docs", | |
| "steps": [ | |
| { | |
| "tool": "get_backlinks", | |
| "input": { | |
| "path": "api/design.md" | |
| }, | |
| "output": [ | |
| { | |
| "path": "guides/architecture.md", | |
| "title": "Architecture Overview" | |
| }, | |
| { | |
| "path": "api/endpoints.md", | |
| "title": "API Endpoints" | |
| } | |
| ] | |
| }, | |
| { | |
| "tool": "read_note", | |
| "input": { | |
| "path": "guides/architecture.md" | |
| } | |
| } | |
| ] | |
| } | |
| ] | |
| }, | |
| "validation": { | |
| "description": "Input validation rules enforced by FastMCP/Pydantic", | |
| "rules": { | |
| "notePath": { | |
| "pattern": "^[^/].*\\.md$", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "mustNotContain": ["..", "\\"], | |
| "mustEndWith": ".md", | |
| "invalidChars": ["<", ">", ":", "\"", "|", "?", "*"] | |
| }, | |
| "noteBody": { | |
| "maxLength": 1048576, | |
| "encoding": "UTF-8" | |
| }, | |
| "searchQuery": { | |
| "minLength": 1, | |
| "maxLength": 256 | |
| }, | |
| "folder": { | |
| "maxLength": 256, | |
| "optional": true | |
| }, | |
| "metadata": { | |
| "type": "object", | |
| "reservedFields": ["version"], | |
| "tagsFormat": "array of strings" | |
| } | |
| } | |
| } | |
| } | |