@dataville/dataville-mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,5 +1,13 @@
 # dataville-mcp
 
+[![M8ven Score](https://m8ven.ai/badge/mcp/datavilleorg-dataville-mcp-u1eou7?v=6abe1c0b98731d0af6f8978f1b3778e6)](https://m8ven.ai/mcp/datavilleorg-dataville-mcp-u1eou7?s=readme)
+[![npm](https://img.shields.io/npm/v/@dataville/dataville-mcp)](https://www.npmjs.com/package/@dataville/dataville-mcp)
+[![CI](https://github.com/datavilleorg/dataville-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/datavilleorg/dataville-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=dataville&config=eyJ1cmwiOiJodHRwczovL2FwaS5kYXRhdmlsbGUuY29tL21jcCJ9)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Dataville-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=dataville&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.dataville.com%2Fmcp%22%7D)
+
 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 —
@@ -15,9 +23,45 @@ Requires a Dataville API key — get one from the [Dataville dashboard](https://
 - `list_dataville_sources` — lists the data sources available via `search_dataville`.
 - `search_dataville` — query a data source: `{ source, keywords, params? }`.
 
+## What you can ask
+
+Once connected, ask in plain language and the client picks the source:
+
+- "Find an arXiv paper on retrieval-augmented generation and summarize it."
+- "What did Apple report in its latest SEC filing?"
+- "What's the median household income in Travis County, Texas, per the US Census?"
+- "How much protein is in 100 g of cooked lentils, according to USDA FoodData?"
+- "Look up the `requests` package on PyPI — what's the latest version and license?"
+
 ## 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.
+Cursor and VS Code users can use the install buttons at the top of this page.
+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
 {
@@ -35,7 +79,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
 
@@ -46,6 +119,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
@@ -58,4 +147,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.4";
+export const VERSION = "0.1.6";
 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/index.js

@@ -1,44 +1,9 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { searchDataSource, VERSION } from "./client.js";
-import { DATAVILLE_SOURCES } from "./sources.js";
-const server = new McpServer({
-    name: "dataville-mcp-server",
-    version: VERSION,
-});
-server.registerTool("list_dataville_sources", {
-    title: "List Dataville data sources",
-    description: "List the data sources available through Dataville's search_dataville tool.",
-    inputSchema: {},
-}, async () => ({
-    content: [{ type: "text", text: JSON.stringify(DATAVILLE_SOURCES, null, 2) }],
-}));
-server.registerTool("search_dataville", {
-    title: "Search a Dataville data source",
-    description: "Query one of Dataville's data sources (see list_dataville_sources for valid source names) with a keyword string and optional query params.",
-    inputSchema: {
-        source: z.string().describe("Data source name, e.g. 'wikipedia', 'arxiv', 'edgar'"),
-        keywords: z.string().describe("Search keywords or identifier for the query"),
-        params: z
-            .record(z.union([z.string(), z.number(), z.boolean()]))
-            .optional()
-            .describe("Optional additional query parameters"),
-    },
-}, async ({ source, keywords, params }) => {
-    try {
-        const result = await searchDataSource(source, keywords, params);
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: "text", text: message }], isError: true };
-    }
-});
+import { createServer } from "./server.js";
 async function main() {
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await createServer().connect(transport);
 }
 main().catch((error) => {
     console.error("Fatal error starting Dataville MCP server:", error);

package/dist/server.js

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { searchDataSource, VERSION } from "./client.js";
+import { DATAVILLE_SOURCES } from "./sources.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "dataville-mcp-server",
+        version: VERSION,
+    });
+    server.registerTool("list_dataville_sources", {
+        title: "List Dataville data sources",
+        description: "List the data sources available through Dataville's search_dataville tool.",
+        inputSchema: {},
+        // Returns a static list bundled with the server; makes no network calls.
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => ({
+        content: [{ type: "text", text: JSON.stringify(DATAVILLE_SOURCES, null, 2) }],
+    }));
+    server.registerTool("search_dataville", {
+        title: "Search a Dataville data source",
+        description: "Query one of Dataville's data sources (see list_dataville_sources for valid source names) with a keyword string and optional query params.",
+        inputSchema: {
+            source: z.string().describe("Data source name, e.g. 'wikipedia', 'arxiv', 'edgar'"),
+            keywords: z.string().describe("Search keywords or identifier for the query"),
+            params: z
+                .record(z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe("Optional additional query parameters"),
+        },
+        // A GET against the Dataville API, which fronts external data sources.
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ source, keywords, params }) => {
+        try {
+            const result = await searchDataSource(source, keywords, params);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: message }], isError: true };
+        }
+    });
+    return server;
+}

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.4",
+  "version": "0.1.6",
+  "mcpName": "com.dataville/dataville-mcp",
   "description": "MCP server exposing Dataville's data source API as tools for MCP clients",
   "private": false,
   "license": "MIT",