@dataville/dataville-mcp 0.1.3 → 0.1.5

package/README.md

@@ -2,6 +2,12 @@
 
 MCP server exposing Dataville's data source API as tools for MCP clients (Claude Desktop, Claude Code, etc.).
 
+[Dataville](https://dataville.com) is a unified REST API over ten public datasets —
+Wikipedia, arXiv, Project Gutenberg, US Census, USDA FoodData, Papers with Code,
+SEC EDGAR, OpenAlex, PyPI, and Stack Exchange — behind one interface and one API
+key, with CSV/Parquet export and SQL query support. This package lets an MCP
+client search any of those sources as a tool call.
+
 Requires a Dataville API key — get one from the [Dataville dashboard](https://app.dataville.com/api-keys).
 
 ## Tools
@@ -11,7 +17,32 @@ Requires a Dataville API key — get one from the [Dataville dashboard](https://
 
 ## Setup
 
-Add this to your MCP client config (Claude Code / Claude Desktop), with `DATAVILLE_API_KEY` set to your own key:
+This package is a local (stdio) MCP server: the client launches it on your
+machine via `npx`. If you don't need it running locally, connecting to
+Dataville's hosted endpoint instead takes one line and no install.
+
+### Hosted, in one line (no install)
+
+Dataville also serves MCP directly over HTTP, so a client can connect without
+running anything locally — no Node, no config file, no restart:
+
+```bash
+claude mcp add --transport http dataville https://api.dataville.com/mcp
+```
+
+That works with no credentials at all (anonymous limits). Add
+`--header "Authorization: Bearer dataville_your_key_here"` for the full quota.
+Other clients take the same URL; the app's Integrations page has the exact
+snippet for each. Use the hosted endpoint unless you specifically want to pin a
+version or work offline — the rest of this section covers that local setup.
+
+### Prerequisites
+
+- **Node.js** (LTS) installed — this is what runs `npx`. Without it the server
+  fails to start. Check with `node --version`.
+- A **Dataville API key** — get one from https://app.dataville.com/api-keys.
+
+The config block is the same everywhere; only *where* you put it differs:
 
 ```json
 {
@@ -29,7 +60,36 @@ Add this to your MCP client config (Claude Code / Claude Desktop), with `DATAVIL
 
 No install step needed — `npx` fetches and runs the package on demand.
 
-`DATAVILLE_API_BASE_URL` is optional and defaults to `https://api.dataville.com`; set it to `http://localhost:5000` to point at a local backend during development.
+### Claude Desktop
+
+1. Open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+2. Add the block above (merge into `mcpServers` if the file already has one),
+   with your real key.
+3. **Fully quit and reopen** Claude Desktop — quit from the menu bar / system
+   tray, not just closing the window.
+4. The dataville tools now appear under the tools icon in the chat box, and
+   Settings → Developer shows `dataville` running.
+
+Note: the server appears as **tools**, not in the **Connectors** directory —
+that directory only lists remote (hosted) connectors and will not find a local
+server. Ask naturally ("get Apple's latest revenue from dataville") and the
+client calls the tool.
+
+### Claude Code
+
+```bash
+claude mcp add dataville -e DATAVILLE_API_KEY=dataville_your_key_here -- npx -y @dataville/dataville-mcp
+```
+
+Restart the session so the tools load. Add `-s user` to make it available in
+every project instead of just the current one.
+
+### Configuration
+
+`DATAVILLE_API_BASE_URL` is optional and defaults to `https://api.dataville.com`;
+set it to `http://localhost:5000` to point at a local backend during development.
 
 ### Running from source
 
@@ -40,6 +100,22 @@ npm install
 npm run build
 ```
 
+## Check that it works
+
+Ask your client one of these. Each answer is checkable on purpose — a model that
+skipped the tool and answered from memory sounds just as confident, so a reply
+on its own proves nothing.
+
+| Ask | What proves it |
+| --- | --- |
+| `Which data sources does Dataville have?` | Calls `list_dataville_sources` and names all eleven. |
+| `Using Dataville, what is the latest version of the requests package on PyPI?` | A version you can confirm on pypi.org — and it moves, so it can't come from memory. |
+| `Using Dataville, get the latest SEC filing for AAPL and its revenue.` | A form type, filing date, revenue figure, and a sec.gov link to open. |
+| `Using Dataville, how much protein is in 100g of uncooked quinoa?` | The exact USDA figure, 14.1 g per 100 g. |
+
+Clients show when a tool ran. If you don't see that, say "use dataville" in the
+prompt to make it explicit, and check the answer against the source.
+
 ## Development
 
 ```bash
@@ -52,4 +128,12 @@ npm run build  # tsc
 
 Publishes run from CI via npm trusted publishing (OIDC) — no tokens are stored.
 To cut a release: bump the version, update `CHANGELOG.md`, then publish a GitHub
-Release for the new tag. The `Publish` workflow builds, tests, and publishes to npm.
+Release for the new tag. The `Publish` workflow builds, tests, and publishes to npm,
+then publishes `server.json` to the [MCP Registry](https://registry.modelcontextprotocol.io)
+(its version is set from `package.json`, so don't bump it by hand).
+
+The registry name `com.dataville/dataville-mcp` is authorized by a DNS TXT record
+on the `dataville.com` apex (`v=MCPv1; k=ed25519; p=<public key>`), checked
+against the Ed25519 private key in the `MCP_PRIVATE_KEY` repo secret (hex). If the
+`mcp-registry` job fails at login, check that record and secret, then re-run just
+that job.

package/dist/client.js

@@ -1,6 +1,6 @@
 const DEFAULT_BASE_URL = "https://api.dataville.com";
 // Keep in sync with package.json version (enforced by a test).
-export const VERSION = "0.1.3";
+export const VERSION = "0.1.5";
 const USER_AGENT = `dataville-mcp/${VERSION}`;
 export class DatavilleApiError extends Error {
     status;
@@ -35,6 +35,14 @@ function getConfig() {
 }
 export async function searchDataSource(source, keywords, params) {
     const { apiKey, baseUrl } = getConfig();
+    // encodeURIComponent leaves "." alone, and URL resolution collapses a "." or
+    // ".." segment — so source ".." would send the user's key to /<keywords>
+    // instead of a data route.
+    for (const [name, value] of [["source name", source], ["search term", keywords]]) {
+        if (value === "." || value === "..") {
+            throw new Error(`"${value}" is not a valid ${name}. Use list_dataville_sources to see valid source names.`);
+        }
+    }
     const url = new URL(`/${encodeURIComponent(source)}/${encodeURIComponent(keywords)}`, baseUrl);
     if (params) {
         for (const [key, value] of Object.entries(params)) {

package/dist/sources.js

@@ -13,5 +13,5 @@ export const DATAVILLE_SOURCES = [
     { name: "openalex", description: "OpenAlex scholarly works" },
     { name: "pypi", description: "PyPI package metadata" },
     { name: "stackexchange", description: "Stack Exchange Q&A" },
-    { name: "news", description: "News front-page headlines and summaries" },
+    { name: "news", description: "Front-page news headlines from a historical archive (not live/current news)" },
 ];

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@dataville/dataville-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
+  "mcpName": "com.dataville/dataville-mcp",
   "description": "MCP server exposing Dataville's data source API as tools for MCP clients",
   "private": false,
   "license": "MIT",