@anyproto/anytype-mcp 1.0.5 → 1.0.7

package/.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Run linter
         run: npm run lint
 
-  type-check:
+  typecheck:
     runs-on: ubuntu-latest
 
     steps:
@@ -46,7 +46,7 @@ jobs:
         run: npm install
 
       - name: Run type checks
-        run: npm run type-check
+        run: npm run typecheck
 
   build:
     runs-on: ubuntu-latest
@@ -65,3 +65,21 @@ jobs:
 
       - name: Build extension
         run: npm run build
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests
+        run: npm run test

package/.github/workflows/release.yml

@@ -27,7 +27,13 @@ jobs:
         run: npm install
 
       - name: Run type checks
-        run: npm run type-check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build project
+        run: npm run build
 
       - name: Publish to npm
         run: npm publish --access public

package/CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Commands
+
+### Development
+- `npm install -D` - Install all dependencies including devDependencies
+- `npm run dev` - Start the development server with file watching (uses tsx watch)
+- `npm run build` - Build the TypeScript project and generate CLI binary (bin/cli.mjs)
+
+### Testing
+- `npm test` - Run all tests once with Vitest
+- `npm run test:dev` - Run tests in watch mode
+- Run a specific test file: `npx vitest run src/openapi/__tests__/parser.test.ts`
+
+### Code Quality
+- `npm run lint` - Check code formatting with ESLint
+- `npm run lint:fix` - Auto-fix formatting issues with ESLint
+- `npm run format` - Auto-fix formatting issues with Prettier
+- `npm run typecheck` - Run TypeScript type checking without emitting files
+
+### Utility Scripts
+- `npm run parse-openapi` - Parse OpenAPI specification
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server that bridges Anytype's API with AI assistants. The architecture follows a proxy pattern where OpenAPI specifications are dynamically converted to MCP tools.
+
+### Core Components
+
+**MCP Proxy Layer (`src/mcp/proxy.ts`)**
+- Central orchestrator that implements the MCP server protocol
+- Converts OpenAPI operations to MCP tools dynamically at runtime
+- Handles tool listing and execution through the MCP protocol
+- Maintains a lookup table mapping MCP tool names to OpenAPI operations
+
+**OpenAPI Parser (`src/openapi/parser.ts`)**
+- Converts OpenAPI schemas to JSON Schema format for MCP compatibility
+- Handles $ref resolution with cycle detection
+- Supports multipart/form-data for file uploads
+- Generates MCP tool definitions from OpenAPI paths and operations
+
+**HTTP Client (`src/client/http-client.ts`)**
+- Built on openapi-client-axios for OpenAPI-aware HTTP requests
+- Handles authentication headers from environment variables
+- Supports file uploads via FormData
+- Executes OpenAPI operations with proper parameter mapping
+
+**Server Initialization (`src/init-server.ts`)**
+- Loads OpenAPI spec from URL (default: local Anytype API) or file
+- Initializes the MCP proxy with the spec
+- Connects to stdio transport for communication
+
+### Key Design Patterns
+
+1. **Dynamic Tool Generation**: Tools are not hardcoded but generated from the OpenAPI spec at runtime, making the server adaptable to API changes.
+
+2. **Header Injection**: Authentication and version headers are parsed from `OPENAPI_MCP_HEADERS` environment variable and injected into all requests.
+
+3. **Operation Mapping**: Each OpenAPI operation becomes an MCP tool with a naming convention: `{tag}-{operationId}`.
+
+4. **Schema Caching**: The parser maintains a cache of resolved schemas to handle circular references and improve performance.
+
+## Testing Strategy
+
+Tests use Vitest and are colocated with source files in `__tests__` directories. Key test areas:
+- OpenAPI to MCP conversion logic
+- HTTP client behavior including file uploads
+- MCP proxy tool execution
+- Multipart form data handling
+
+## Code Style
+
+- Prettier with 120 character line width
+- Double quotes for strings
+- Automatic import organization via prettier-plugin-organize-imports
+- TypeScript strict mode enabled

package/{LICENSE → LICENSE.md}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Snaggle.ai
+Copyright (c) 2023 Any Association
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +12,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -38,7 +38,9 @@ npx -y @anyproto/anytype-mcp get-key
 
 ### 2. Configure Your MCP Client
 
-Add the following configuration to your MCP client settings:
+#### Claude Desktop, Cursor, Windsurf, Raycast, etc.
+
+Add the following configuration to your MCP client settings after replacing `<YOUR_API_KEY>` with your actual API key:
 
 ```json
 {
@@ -54,7 +56,15 @@ Add the following configuration to your MCP client settings:
 }
 ```
 
-> **Tip:** After creating an API key in Anytype, you can copy a ready-to-use configuration snippet with your API key already filled in from the API Keys section.
+> **Tip:** After creating an API key in Anytype, you can copy that ready-to-use configuration snippet with your API key already filled in from the API Keys section.
+
+#### Claude Code (CLI)
+
+Run this command to add the Anytype MCP server after replacing `<YOUR_API_KEY>` with your actual API key:
+
+```bash
+claude mcp add anytype -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <YOUR_API_KEY>", "Anytype-Version":"2025-05-20"}' -s user -- npx -y @anyproto/anytype-mcp
+```
 
 <details>
 <summary>Alternative: Global Installation</summary>