Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit177f0af

Browse files
authored
docs: make README more appealing (#15)
1 parentd11284b commit177f0af

File tree

1 file changed

+177
-104
lines changed

1 file changed

+177
-104
lines changed

‎README.md

Lines changed: 177 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,126 @@
1-
#Algolia NodeJS MCP implementation
1+
#🔍 Algolia Node.js MCP
2+
3+
>Connect Claude Desktop to your Algolia data using the Model Context Protocol (MCP)
4+
5+
<palign="center">
6+
<ahref="#-quick-start">Quick Start</a> •
7+
<ahref="#-features">Features</a> •
8+
<ahref="#-usage-examples">Usage Examples</a> •
9+
<ahref="#-installation">Installation</a> •
10+
<ahref="#%EF%B8%8F-configuration">Configuration</a> •
11+
<ahref="#-development">Development</a> •
12+
<ahref="#-troubleshooting">Troubleshooting</a> •
13+
<ahref="#-contributing">Contributing</a> •
14+
<ahref="#-license">License</a>
15+
</p>
216

317
https://github.com/user-attachments/assets/c36a72e0-f790-4b3f-8720-294ab7f5f6eb
418

5-
-[Algolia NodeJS MCP implementation](#algolia-nodejs-mcp-implementation)
6-
-[Running the MCP Server (Mac Only)](#running-the-mcp-server-mac-only)
7-
-[What can I ask for?](#what-can-i-ask-for)
8-
-[Account](#account)
9-
-[Apps](#apps)
10-
-[Search](#search)
11-
-[AB Testing](#ab-testing)
12-
-[Analytics](#analytics)
13-
-[Monitoring](#monitoring)
14-
-[CLI options](#cli-options)
15-
-[List available commands](#list-available-commands)
16-
-[Server options](#server-options)
17-
-[Setup dev environment](#setup-dev-environment)
18-
-[Testing and debugging](#testing-and-debugging)
19+
##✨ Quick Start
1920

20-
##Running the MCP Server (Mac Only)
21+
1.**Download** the latest release from our[GitHub Releases](https://github.com/algolia/mcp-node/releases)
22+
2.**Authenticate** with your Algolia account
23+
3.**Connect** to Claude Desktop
24+
4. Start asking questions about your Algolia data!
2125

22-
1. Download the latest version of the Algolia MCP server athttps://github.com/algolia/mcp-node/releases
26+
>[!NOTE]
27+
>For step-by-step instructions, follow the[installation guide](#-installation) and[configuration for Claude Desktop](#%EF%B8%8F-configuration).
2328
24-
2. Extract the Zip file
29+
##🚀 Features
2530

26-
3. From a terminal, run`xattr -r -d com.apple.quarantine <path_to_executable>`
31+
Algolia Node.js MCP enables natural language interactions with your Algolia data through Claude Desktop. This implementation allows you to:
2732

28-
>[!IMPORTANT]
29-
>Why do you need to run this command?
30-
>This executable is not signed because I don't have a payed Apple Developer Account.
31-
>This means that macOS will "quarantine" it by default when it is downloaded from the internet.
32-
>The command remove the quarantine, allowing you to run the program. If you don't trust the build,
33-
>you can always build it yourself from source with`npm run build -- --outfile dist/algolia-mcp` (see development environment setup below) 😄.
33+
-**Search and manipulate** indices with natural language
34+
-**Analyze** search metrics and performance
35+
-**Monitor** application status and incidents
36+
-**Visualize** your data with AI-generated charts and graphs
37+
-**Integrate** seamlessly with Claude Desktop through the Model Context Protocol
3438

35-
4. Run <path_to_executable> authenticate. This will open a tab in your browser inviting you to authenticate with
36-
the Algolia Dashboard.
39+
##🔮 Usage Examples
3740

38-
5. Configure Claude Desktop
41+
Here are some example prompts to get you started:
3942

40-
>[!TIP]
41-
>You can refer to the official documenation herehttps://modelcontextprotocol.io/quickstart/user
42-
43-
```json
44-
{
45-
"mcpServers": {
46-
"algolia-mcp": {
47-
"command":"<path_to_executable>"
48-
}
49-
}
50-
}
43+
###Account Management
44+
```
45+
"What is the email address associated with my Algolia account?"
46+
"How many API keys do I have in my account?"
5147
```
5248

53-
6. Start Claude Desktop
54-
55-
##What can I ask for?
56-
57-
Algolia Node MCP lets you interact with your Algolia apps and indices. Here are some example prompts to get you started:
58-
59-
###Account
60-
61-
- "What is the email address associated to my account?"
62-
63-
###Apps
64-
65-
- "List all my apps Algolia apps."
66-
- "List all the apps that I own."
67-
- "What's the ID for app Latency?"
68-
69-
###Search
70-
71-
- "Search all items in the products index of app Latency where brand = 'Nike' and price < 100."
72-
- "Retrieve the top 10 best tech books and save them in the books index of app Latency with their ISBN at the objectID."
73-
74-
###AB Testing
75-
76-
- "Do I have any AB Tests currently running on application <application_id>?"
77-
78-
###Analytics
49+
###Applications
50+
```
51+
"List all my Algolia apps and their creation dates."
52+
"What indices are in my 'E-commerce' application?"
53+
"Show me the configuration for my 'products' index."
54+
```
7955

80-
- "I have an index named <index_name> on application <application_id>, can you generate a graph for no results rate in DE region over the past month? Please use react and recharts."
56+
###Search & Indexing
57+
```
58+
"Search my 'products' index for Nike shoes under $100."
59+
"Add these 10 books to my 'library' index using their ISBNs as objectIDs."
60+
"How many records do I have in my 'customers' index?"
61+
```
8162

82-
###Monitoring
63+
###Analytics & Insights
64+
```
65+
"Generate a chart showing my search volume for the past month."
66+
"What's the no-results rate for my 'products' index in the EU region? Generate a graph using React and Recharts."
67+
"Show me the top 10 searches with no results from last week."
68+
```
8369

84-
- "Are there any incidents going on at Algolia currently?"
70+
###Monitoring & Performance
71+
```
72+
"Are there any ongoing incidents at Algolia?"
73+
"What's the current latency for my US application?"
74+
"Show me a visualization of my API usage over the past week."
75+
```
8576

86-
###Usage
77+
>[!TIP]
78+
>Try providing your specific application and index in your initial prompt to avoid unnecessary back and forth.
79+
80+
##📦 Installation
81+
82+
###macOS
83+
84+
1. Download the latest release from[GitHub Releases](https://github.com/algolia/mcp-node/releases)
85+
2. Extract the`.zip` file
86+
3. From your terminal, remove quarantine flag to allow execution:
87+
```sh
88+
xattr -r -d com.apple.quarantine<path_to_executable>
89+
```
90+
>**Note:** This step is necessary as the executable is not signed with an Apple Developer account. If you prefer, you can build from source instead.
91+
4. Run the authentication command:
92+
```sh
93+
<path_to_executable> authenticate
94+
```
95+
This will open your browser to authenticate with the Algolia Dashboard.
96+
97+
###Windows & Linux
98+
99+
*Coming soon.*
100+
101+
##⚙️ Configuration
102+
103+
###Claude Desktop Setup
104+
105+
1. Open Claude Desktop settings
106+
2. Add the following to your configuration:
107+
```json
108+
{
109+
"mcpServers": {
110+
"algolia-mcp": {
111+
"command":"<path_to_executable>"
112+
}
113+
}
114+
}
115+
```
116+
3. Restart Claude Desktop
87117

88-
- "I have an Algolia application with id <application_id>. Can you show me a bar chart of my records usage over the past week?"
118+
>[!TIP]
119+
>You can refer to the[official documentation](https://modelcontextprotocol.io/quickstart/user) for Claude Desktop.
89120
90-
##CLIoptions
121+
###CLIOptions
91122

92-
###List available commands
123+
####Available Commands
93124

94125
```sh
95126
Usage: algolia-mcp [options] [command]
@@ -105,7 +136,7 @@ Commands:
105136
help [command] displayhelpforcommand
106137
```
107138

108-
###Serveroptions
139+
####ServerOptions
109140

110141
```sh
111142
Usage: algolia-mcp start-server [options]
@@ -118,45 +149,87 @@ Options:
118149
-h, --help displayhelpforcommand
119150
```
120151

121-
##Setup dev environment
152+
##🛠 Development
122153

123-
You need at least Node 22
154+
###Requirements
124155

125-
```sh
126-
git clone https://github.com/algolia/mcp-node
127-
cd mcp-node
128-
npm i
129-
```
156+
- Node.js 22 or higher
157+
- npm
130158

131-
And then you'll need to configure Claude Desktop like so:
132-
133-
```json
134-
{
135-
"mcpServers": {
136-
"algolia-mcp": {
137-
"command":"<PATH_TO_BIN>/node",
138-
"args": [
139-
"--experimental-strip-types",
140-
"--no-warnings=ExperimentalWarning",
141-
"<PATH_TO_PROJECT>/src/app.ts"
142-
]
143-
}
144-
}
145-
}
146-
```
159+
###Setup Development Environment
147160

148-
>[!TIP]
149-
>You'll need to restart Claude Desktop every time you make a modification.
161+
1. Clone the repository:
162+
```sh
163+
git clone https://github.com/algolia/mcp-node
164+
cd mcp-node
165+
npm install
166+
```
150167

151-
##Testing and debugging
168+
2. Configure Claude Desktop for development:
169+
```json
170+
{
171+
"mcpServers": {
172+
"algolia-mcp": {
173+
"command":"<PATH_TO_BIN>/node",
174+
"args": [
175+
"--experimental-strip-types",
176+
"--no-warnings=ExperimentalWarning",
177+
"<PATH_TO_PROJECT>/src/app.ts"
178+
]
179+
}
180+
}
181+
}
182+
```
152183

153-
You can test and debug tools using the[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
184+
>**Note:**You'll need to restart Claude Desktop after making code changes.
154185
155-
Navigate to the respository and run the`debug` script:
186+
###Build
156187

157188
```sh
158-
cd path/to/mcp-node
159-
npm run debug
189+
npm run build -- --outfile dist/algolia-mcp
160190
```
161191

162-
Then go tohttp://127.0.0.1:6274/ and click**Connect** to start the server.
192+
###Testing and Debugging
193+
194+
Use the[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for testing and debugging:
195+
196+
1. Run the debug script:
197+
```sh
198+
cd mcp-node
199+
npm run debug
200+
```
201+
202+
2. Openhttp://127.0.0.1:6274/ in your browser
203+
3. Click**Connect** to start the server
204+
4. Send test requests through the inspector interface
205+
206+
##🔧 Troubleshooting
207+
208+
###Common Issues
209+
210+
-**"App not responding" error:** Ensure you've removed the quarantine attribute on macOS
211+
-**Authentication failures:** Try logging out and authenticating again
212+
-**Claude can't access tools:** Verify your MCP configuration in Claude Desktop settings
213+
214+
###Logs and Diagnostics
215+
216+
Log files are stored in:
217+
- macOS:`~/Library/Logs/algolia-mcp/`
218+
- Windows:`%APPDATA%\algolia-mcp\logs\`
219+
- Linux:`~/.config/algolia-mcp/logs/`
220+
221+
##👥 Contributing
222+
223+
We welcome contributions to Algolia Node.js MCP! Here's how you can help:
224+
225+
1. Fork the repository
226+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
227+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
228+
4. Push to the branch (`git push origin feature/amazing-feature`)
229+
5. Open a pull request
230+
231+
---
232+
233+
<palign="center">
234+
Made with ❤️ by Algolia
235+
</p>

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp