@aventurevc/mcp-server 0.7.332 → 0.8.1

package/README.md

@@ -1,37 +1,105 @@
-# aventure-mcp
+# aVenture MCP server
 
-Public aVenture Streamable HTTP MCP server. Most clients need no install: the
-[MCP quickstart](https://docs.aventure.vc/mcp) connects them to the hosted server
-at `https://mcp.aventure.vc/mcp`. Self-host with this package when your client
-cannot complete an OAuth flow.
+Give an AI client access to aVenture's research data on companies, people, funding,
+and news through the Model Context Protocol (MCP).
 
-Requires Node.js 24.18 or later in the 24.x series.
+Most clients need no install: connect them to the hosted server at
+`https://mcp.aventure.vc/mcp` and sign in with OAuth. Install this package only to
+run the server yourself, for example when your client cannot complete an OAuth
+sign-in. The [aVenture MCP quickstart](https://docs.aventure.vc/mcp) covers both
+paths.
 
-## Install and start
+## Connect to the hosted server
+
+Configure your client with these settings:
+
+- URL: `https://mcp.aventure.vc/mcp`
+- Transport: Streamable HTTP
+- OAuth client ID: `KL7mINzGk0le0QiD`
+- Client secret: none; this is a public client
+
+The client discovers the authorization server from the MCP URL and signs in with
+authorization code and PKCE. Dynamic client registration is disabled, so enter the
+client ID explicitly. A client that accepts only a URL fails with
+`does not support dynamic client registration`.
+
+For example, add the server to Claude Code for all your projects:
+
+```sh
+claude mcp add --scope user --transport http \
+  --client-id KL7mINzGk0le0QiD --callback-port 6276 \
+  aventure https://mcp.aventure.vc/mcp
+```
+
+Then run `/mcp` in Claude Code, select `aventure`, and complete browser sign-in.
+
+The registered redirect URIs are:
+
+- `http://127.0.0.1/callback`
+- `http://localhost/callback`
+- `https://chatgpt.com/connector_platform_oauth_redirect`
+- `https://claude.ai/api/mcp/auth_callback`
+
+A loopback redirect may use any available port, such as
+`http://127.0.0.1:6276/callback`, as long as it keeps the `/callback` path.
+
+To test the sign-in flow without a client, run the MCP Inspector in a terminal,
+sign in to aVenture, and approve access. The Inspector lists the tools when sign-in
+succeeds.
+
+```sh
+npx @modelcontextprotocol/inspector@2.6.0 --cli \
+  --server-url https://mcp.aventure.vc/mcp \
+  --client-id KL7mINzGk0le0QiD \
+  --callback-url http://127.0.0.1:6276/callback \
+  --method tools/list
+```
+
+## Run the server yourself
+
+The server requires Node.js 24.18 or later in the 24.x series. Installation fails
+on any other major version.
 
 ```sh
 npm install --global @aventurevc/mcp-server --@aventurevc:registry=https://registry.npmjs.org/
-aventure-mcp-server --help
 aventure-mcp-server
 ```
 
-The server listens at `http://localhost:3333/mcp`. Leave it running while your
-MCP client connects. It starts without a static credential; each MCP request needs
-a user credential. This package uses Streamable HTTP, so configure a URL instead
-of a stdio command.
+The `--@aventurevc:registry` flag makes npm install from the public npm registry
+even when your npm configuration maps the `@aventurevc` scope somewhere else. The
+package installs the same server under two command names, `aventure-mcp-server`
+and `aventure-mcp`.
+
+The server listens at `http://localhost:3333/mcp` and accepts connections from this
+computer only. Keep it running while your client is connected. It speaks
+Streamable HTTP, not stdio, so configure your client with a URL, not a command.
+
+| Setting | What it changes |
+| --- | --- |
+| `AVENTURE_MCP_PORT` environment variable | Listening port (default `3333`) |
+| `AVENTURE_MCP_PATH` environment variable | MCP route (default `/mcp`) |
+| `AVENTURE_MCP_JSON_LIMIT` environment variable | Maximum request body size |
+| `--host <address>` option | Network address to bind instead of `127.0.0.1`; `0.0.0.0` exposes the server to your network |
 
-## Connect with a personal API key
+Update the client URL when you change the port or route.
 
-Sign in, open [aventure.vc/settings/api-keys](https://aventure.vc/settings/api-keys),
-and choose **Add new key**. Store the key in your MCP client's secret storage.
-The HTTP request must carry `Authorization: Bearer <personal-api-key>`.
+### Authenticate with a personal API key
 
-For clients supporting `mcpServers` URL configuration:
+A self-hosted server has no OAuth sign-in and no credential of its own. Every
+request must carry a personal API key as a bearer token.
+
+1. Sign in to aVenture and create a key in
+   [aVenture API key settings](https://aventure.vc/settings/api-keys).
+2. Store the key in your MCP client's secret storage. Never commit it to a file.
+3. Configure the client to send `Authorization: Bearer <personal-api-key>`.
+
+For clients that read an `mcpServers` configuration:
 
 ```json
 {
   "mcpServers": {
     "aventure": {
+      "type": "http",
       "url": "http://localhost:3333/mcp",
       "headers": {
         "Authorization": "Bearer <personal-api-key>"
@@ -41,53 +109,49 @@ For clients supporting `mcpServers` URL configuration:
 }
 ```
 
-Replace the placeholder through your client's credential configuration; its secret
-interpolation syntax may differ.
+Replace `<personal-api-key>` using your client's secret interpolation syntax, which
+differs between clients. A request without a key receives status `401`.
 
-## Authenticate with native OAuth
+## Verify the connection
 
-Connect to the hosted server at `https://mcp.aventure.vc/mcp` with an
-OAuth-capable client. Configure the public client ID `KL7mINzGk0le0QiD`;
-no client secret is required. The client discovers the authorization server
-from the MCP endpoint and uses authorization code with PKCE. Dynamic client
-registration is disabled.
+List the tools, call `aventure_status`, and then call `aventure_help`.
 
-The registered redirect URIs are:
+| Tool | What it does |
+| --- | --- |
+| `aventure_status` | Returns API status, host, and the access your credential carries |
+| `aventure_help` | Finds the operation for a task and lists the inputs it needs |
+| `aventure_search` | Runs a search operation over companies, people, news, or content |
+| `aventure_lookup` | Resolves a name, URL, domain, slug, or other identifier to a record |
+| `aventure_read` | Reads one record or the records attached to it |
 
-- `http://127.0.0.1/callback`
-- `http://localhost/callback`
-- `https://chatgpt.com/connector_platform_oauth_redirect`
-- `https://claude.ai/api/mcp/auth_callback`
+Accounts with write permission also see `aventure_write` and `aventure_delete`,
+which change shared data immediately. The tool list reflects the signed-in
+account's permissions, and the API checks permission again on every call.
 
-Loopback redirects may use an available port, such as
-`http://127.0.0.1:6276/callback`; keep the `/callback` path. A client using
-another callback path needs its own registered OAuth application.
+## Plans and usage
 
-For example, MCP Inspector 2.6.0 supports these settings:
+Calls count toward your aVenture plan's usage. Some operations, such as
+plain-English search, need a plan that includes them; without one, the API
+responds with status `402`.
 
-```sh
-npx @modelcontextprotocol/inspector@2.6.0 --cli \
-  --server-url https://mcp.aventure.vc/mcp \
-  --client-id KL7mINzGk0le0QiD \
-  --callback-url http://127.0.0.1:6276/callback \
-  --method tools/list
-```
+- Compare plans on the [aVenture pricing page](https://aventure.vc/pricing).
+- Check your plan and current usage in
+  [aVenture subscription settings](https://aventure.vc/settings/subscription).
 
-Run it in an interactive terminal, sign in to aVenture, and approve access.
-The Inspector exchanges the authorization code and lists the MCP tools.
+## Diagnostics
 
-## Verify access
+The server writes diagnostics to standard error. It sends no logs, metrics, or
+error reports to aVenture.
 
-Connect the client, list its tools, and call `aventure_status`, then `aventure_help`.
-The tool list reflects the permissions granted to the signed-in user. The API checks
-permission again when an operation runs.
+## Documentation
 
-Set `AVENTURE_MCP_PORT` or `AVENTURE_MCP_PATH` to change the listener and update
-the client URL to match.
+- [MCP quickstart](https://docs.aventure.vc/mcp)
+- [Authentication guide](https://docs.aventure.vc/authentication)
+- [Error reference](https://docs.aventure.vc/errors)
+- [API reference](https://docs.aventure.vc/api-reference)
 
-## Diagnostics
+The tool catalog is generated from the public aVenture OpenAPI specification.
 
-The public package writes diagnostics to stderr. OTLP logs, Prometheus metrics,
-and Sentry reporting are disabled.
+## License
 
-The tool catalog is generated from the public aVenture OpenAPI spec.
+Apache License 2.0. See the [LICENSE file](LICENSE).