@anyproto/anytype-mcp 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/.github/workflows/ci.yml +20 -2
  2. package/.github/workflows/release.yml +7 -1
  3. package/CLAUDE.md +78 -0
  4. package/{LICENSE → LICENSE.md} +8 -8
  5. package/README.md +20 -6
  6. package/bin/cli.mjs +76 -55
  7. package/package.json +26 -21
  8. package/scripts/__tests__/parse-openapi.test.ts +6 -0
  9. package/scripts/__tests__/start-server.test.ts +42 -0
  10. package/src/client/__tests__/http-client-upload.test.ts +5 -0
  11. package/src/init-server.ts +9 -3
  12. package/src/openapi/__tests__/parser.test.ts +30 -23
  13. package/test_cases/ebay-api.json +0 -2555
  14. package/test_cases/ebay-api.json.tools +0 -3710
package/.github/workflows/ci.yml CHANGED
@@ -30,7 +30,7 @@ jobs:
30
30
  - name: Run linter
31
31
  run: npm run lint
32
32
 
33
- type-check:
33
+ typecheck:
34
34
  runs-on: ubuntu-latest
35
35
 
36
36
  steps:
@@ -46,7 +46,7 @@ jobs:
46
46
  run: npm install
47
47
 
48
48
  - name: Run type checks
49
- run: npm run type-check
49
+ run: npm run typecheck
50
50
 
51
51
  build:
52
52
  runs-on: ubuntu-latest
@@ -65,3 +65,21 @@ jobs:
65
65
 
66
66
  - name: Build extension
67
67
  run: npm run build
68
+
69
+ test:
70
+ runs-on: ubuntu-latest
71
+
72
+ steps:
73
+ - name: Checkout code
74
+ uses: actions/checkout@v4
75
+
76
+ - name: Set up Node.js
77
+ uses: actions/setup-node@v4
78
+ with:
79
+ node-version: "22"
80
+
81
+ - name: Install dependencies
82
+ run: npm install
83
+
84
+ - name: Run tests
85
+ run: npm run test
package/.github/workflows/release.yml CHANGED
@@ -27,7 +27,13 @@ jobs:
27
27
  run: npm install
28
28
 
29
29
  - name: Run type checks
30
- run: npm run type-check
30
+ run: npm run typecheck
31
+
32
+ - name: Run tests
33
+ run: npm run test
34
+
35
+ - name: Build project
36
+ run: npm run build
31
37
 
32
38
  - name: Publish to npm
33
39
  run: npm publish --access public
package/CLAUDE.md ADDED
@@ -0,0 +1,78 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Common Commands
6
+
7
+ ### Development
8
+ - `npm install -D` - Install all dependencies including devDependencies
9
+ - `npm run dev` - Start the development server with file watching (uses tsx watch)
10
+ - `npm run build` - Build the TypeScript project and generate CLI binary (bin/cli.mjs)
11
+
12
+ ### Testing
13
+ - `npm test` - Run all tests once with Vitest
14
+ - `npm run test:dev` - Run tests in watch mode
15
+ - Run a specific test file: `npx vitest run src/openapi/__tests__/parser.test.ts`
16
+
17
+ ### Code Quality
18
+ - `npm run lint` - Check code formatting with ESLint
19
+ - `npm run lint:fix` - Auto-fix formatting issues with ESLint
20
+ - `npm run format` - Auto-fix formatting issues with Prettier
21
+ - `npm run typecheck` - Run TypeScript type checking without emitting files
22
+
23
+ ### Utility Scripts
24
+ - `npm run parse-openapi` - Parse OpenAPI specification
25
+
26
+ ## Architecture Overview
27
+
28
+ 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.
29
+
30
+ ### Core Components
31
+
32
+ **MCP Proxy Layer (`src/mcp/proxy.ts`)**
33
+ - Central orchestrator that implements the MCP server protocol
34
+ - Converts OpenAPI operations to MCP tools dynamically at runtime
35
+ - Handles tool listing and execution through the MCP protocol
36
+ - Maintains a lookup table mapping MCP tool names to OpenAPI operations
37
+
38
+ **OpenAPI Parser (`src/openapi/parser.ts`)**
39
+ - Converts OpenAPI schemas to JSON Schema format for MCP compatibility
40
+ - Handles $ref resolution with cycle detection
41
+ - Supports multipart/form-data for file uploads
42
+ - Generates MCP tool definitions from OpenAPI paths and operations
43
+
44
+ **HTTP Client (`src/client/http-client.ts`)**
45
+ - Built on openapi-client-axios for OpenAPI-aware HTTP requests
46
+ - Handles authentication headers from environment variables
47
+ - Supports file uploads via FormData
48
+ - Executes OpenAPI operations with proper parameter mapping
49
+
50
+ **Server Initialization (`src/init-server.ts`)**
51
+ - Loads OpenAPI spec from URL (default: local Anytype API) or file
52
+ - Initializes the MCP proxy with the spec
53
+ - Connects to stdio transport for communication
54
+
55
+ ### Key Design Patterns
56
+
57
+ 1. **Dynamic Tool Generation**: Tools are not hardcoded but generated from the OpenAPI spec at runtime, making the server adaptable to API changes.
58
+
59
+ 2. **Header Injection**: Authentication and version headers are parsed from `OPENAPI_MCP_HEADERS` environment variable and injected into all requests.
60
+
61
+ 3. **Operation Mapping**: Each OpenAPI operation becomes an MCP tool with a naming convention: `{tag}-{operationId}`.
62
+
63
+ 4. **Schema Caching**: The parser maintains a cache of resolved schemas to handle circular references and improve performance.
64
+
65
+ ## Testing Strategy
66
+
67
+ Tests use Vitest and are colocated with source files in `__tests__` directories. Key test areas:
68
+ - OpenAPI to MCP conversion logic
69
+ - HTTP client behavior including file uploads
70
+ - MCP proxy tool execution
71
+ - Multipart form data handling
72
+
73
+ ## Code Style
74
+
75
+ - Prettier with 120 character line width
76
+ - Double quotes for strings
77
+ - Automatic import organization via prettier-plugin-organize-imports
78
+ - TypeScript strict mode enabled
package/{LICENSE → LICENSE.md} RENAMED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 Snaggle.ai
3
+ Copyright (c) 2023 Any Association
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +12,10 @@ furnished to do so, subject to the following conditions:
12
12
  The above copyright notice and this permission notice shall be included in all
13
13
  copies or substantial portions of the Software.
14
14
 
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
19
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
20
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
21
+ OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # Anytype MCP Server
2
2
 
3
- [![NPM version](https://img.shields.io/npm/v/@anyproto/anytype-mcp.svg)](https://npmjs.org/package/@anyproto/anytype-mcp)
3
+ <a href="https://npmjs.org/package/@anyproto/anytype-mcp"><img src="https://img.shields.io/npm/v/@anyproto/anytype-mcp.svg" alt="NPM version" height="20" /></a>
4
+ <a href="https://cursor.com/install-mcp?name=anytype&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwYW55cHJvdG8lMkZhbnl0eXBlLW1jcCUyMiUyQyUyMmVudiUyMiUzQSU3QiUyMk9QRU5BUElfTUNQX0hFQURFUlMlMjIlM0ElMjIlN0IlNUMlMjJBdXRob3JpemF0aW9uJTVDJTIyJTNBJTVDJTIyQmVhcmVyJTIwJTNDWU9VUl9BUElfS0VZJTNFJTVDJTIyJTJDJTIwJTVDJTIyQW55dHlwZS1WZXJzaW9uJTVDJTIyJTNBJTVDJTIyMjAyNS0wNS0yMCU1QyUyMiU3RCUyMiU3RCU3RA%3D%3D"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add anytype MCP server to Cursor" height="20" /></a>
5
+ <a href="https://lmstudio.ai/install-mcp?name=anytype&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhbnlwcm90by9hbnl0eXBlLW1jcCJdLCJlbnYiOnsiT1BFTkFQSV9NQ1BfSEVBREVSUyI6IntcIkF1dGhvcml6YXRpb25cIjpcIkJlYXJlciA8WU9VUl9BUElfS0VZPlwiLCBcIkFueXR5cGUtVmVyc2lvblwiOlwiMjAyNS0wNS0yMFwifSJ9fQ%3D%3D"><img src="https://files.lmstudio.ai/deeplink/mcp-install-light.svg" alt="Add MCP Server anytype to LM Studio" height="20" /></a>
4
6
 
5
- The Anytype MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server implementation, enabling AI assistants to seamlessly interact with [Anytype's API](https://github.com/anyproto/anytype-api) through natural language.
7
+ The Anytype MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server enabling AI assistants to seamlessly interact with [Anytype's API](https://github.com/anyproto/anytype-api) through natural language.
6
8
 
7
9
  It bridges the gap between AI and Anytype's powerful features by converting Anytype's OpenAPI specification into MCP tools, allowing you to manage your knowledge base through conversation.
8
10
 
@@ -19,9 +21,9 @@ It bridges the gap between AI and Anytype's powerful features by converting Anyt
19
21
  ### 1. Get Your API Key
20
22
 
21
23
  1. Open Anytype
22
- 2. Go to Settings
23
- 3. Navigate to API Keys
24
- 4. Create a new API key
24
+ 2. Go to App Settings
25
+ 3. Navigate to API Keys section
26
+ 4. Click on `Create new` button
25
27
 
26
28
  <details>
27
29
  <summary>Alternative: Get API key via CLI</summary>
@@ -36,7 +38,9 @@ npx -y @anyproto/anytype-mcp get-key
36
38
 
37
39
  ### 2. Configure Your MCP Client
38
40
 
39
- Add the following configuration to your MCP client settings:
41
+ #### Claude Desktop, Cursor, Windsurf, Raycast, etc.
42
+
43
+ Add the following configuration to your MCP client settings after replacing `<YOUR_API_KEY>` with your actual API key:
40
44
 
41
45
  ```json
42
46
  {
@@ -52,6 +56,16 @@ Add the following configuration to your MCP client settings:
52
56
  }
53
57
  ```
54
58
 
59
+ > **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.
60
+
61
+ #### Claude Code (CLI)
62
+
63
+ Run this command to add the Anytype MCP server after replacing `<YOUR_API_KEY>` with your actual API key:
64
+
65
+ ```bash
66
+ 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
67
+ ```
68
+
55
69
  <details>
56
70
  <summary>Alternative: Global Installation</summary>
57
71