ai-resources-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drishtant Ghosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# ai-resources-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server that gives any AI agent the [AI Resources](https://github.com/Drix10/ai-resources) news layer: daily briefings on AI models, companies, funding rounds, tools and research, searchable and citable. It reads the public API of [blogs.drix10.com](https://blogs.drix10.com); no key needed.
+
+| Tool | What it does |
+| --- | --- |
+| `search_briefings(query, category?, limit?, since?)` | Keyword search, newest first. All words must match. `since` is `YYYY-MM-DD`. |
+| `latest(category?, limit?)` | The newest briefings, overall or for one category. |
+| `get_briefing(id)` | Full Markdown of one briefing (URL or slug), with every source link. |
+| `list_categories()` | Every category slug with its briefing count. |
+
+Every result ends with its source link and `Data: github.com/Drix10/ai-resources (CC BY 4.0)`, so answers stay citable.
+
+## Install
+
+> The npm package `ai-resources-mcp` is not published yet. Until it is, run it from a clone:
+> `git clone --depth 1 https://github.com/Drix10/ai-resources && cd ai-resources/mcp && npm ci`,
+> then use `node /full/path/to/ai-resources/mcp/index.js` wherever the snippets below say `npx -y ai-resources-mcp`.
+
+**Claude Code**
+
+```bash
+claude mcp add ai-resources -- npx -y ai-resources-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`) and **Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ai-resources": { "command": "npx", "args": ["-y", "ai-resources-mcp"] }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "ai-resources": { "type": "stdio", "command": "npx", "args": ["-y", "ai-resources-mcp"] }
+  }
+}
+```
+
+or from a terminal: `code --add-mcp "{\"name\":\"ai-resources\",\"command\":\"npx\",\"args\":[\"-y\",\"ai-resources-mcp\"]}"`
+
+On Windows, if a client cannot start `npx`, use `"command": "cmd", "args": ["/c", "npx", "-y", "ai-resources-mcp"]`.
+
+## Settings
+
+`AI_RESOURCES_API_URL`: base URL of the API (default `https://blogs.drix10.com`). Node 18 or later.
+
+## The API underneath
+
+Usable without MCP, from any HTTP client (CORS open, JSON):
+
+- `GET /api/articles?q=&category=&since=&limit=&page=`: `{ items: [{ title, url, slug, category, categorySlug, date, description, headlines, sources: [{ title, url }] }], total, page, limit, totalPages, license }`
+- `GET /api/articles?slug=<slug or URL>`: one item, plus `content` (full Markdown)
+- `GET /api/categories`: `{ items: [{ name, slug, count, url, llms }] }`
+- `GET /llms.txt` and `GET /llms/<category-slug>.txt`: the latest 50 briefings of a category in llms.txt form
+
+## Develop
+
+```bash
+git clone https://github.com/Drix10/ai-resources
+cd ai-resources/mcp
+npm ci
+npm test          # node:test against a stubbed fetch
+```
+
+Issues labelled [`mcp`](https://github.com/Drix10/ai-resources/issues?q=is%3Aissue+is%3Aopen+label%3Amcp) are open for contributors; see [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+Code: [MIT](LICENSE). Data: [Drix10/ai-resources](https://github.com/Drix10/ai-resources), CC BY 4.0.

package/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+
+await createServer().connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "ai-resources-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "mcpName": "io.github.Drix10/ai-resources",
+  "description": "MCP server for the AI Resources knowledge base: search and read daily AI news briefings (models, companies, funding, tools) from any AI agent.",
+  "license": "MIT",
+  "author": "Drix10",
+  "type": "module",
+  "bin": {
+    "ai-resources-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "server.js",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-news",
+    "llm",
+    "agents",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://github.com/Drix10/ai-resources/tree/main/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Drix10/ai-resources.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Drix10/ai-resources/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.0.0"
+  }
+}

package/server.js

@@ -0,0 +1,108 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export const VERSION = '1.0.0';
+export const DATA_LINE = 'Data: github.com/Drix10/ai-resources (CC BY 4.0)';
+export const DEFAULT_BASE = 'https://blogs.drix10.com';
+
+const text = (s) => ({ content: [{ type: 'text', text: s }] });
+const fail = (s) => ({ ...text(`${s}\n${DATA_LINE}`), isError: true });
+
+function formatItem(a, i) {
+  const lines = [`${i + 1}. ${a.title} (${a.date}, ${a.category})`, `   ${a.description}`, `   ${a.url}`];
+  const more = (a.headlines || []).slice(1, 6);
+  if (more.length) lines.push(`   Also in this briefing: ${more.join('; ')}`);
+  const src = (a.sources || []).slice(0, 3).map((s) => s.url);
+  if (src.length) lines.push(`   Sources: ${src.join(' ')}`);
+  return lines.join('\n');
+}
+
+function formatList(data, pageUrl) {
+  if (!data.items?.length) return text(`No briefings found.\nSource: ${pageUrl}\n${DATA_LINE}`);
+  const body = data.items.map(formatItem).join('\n\n');
+  return text(`${data.items.length} of ${data.total} briefings, newest first:\n\n${body}\n\nSource: ${pageUrl}\n${DATA_LINE}`);
+}
+
+// All tools read the public JSON API of the blog (see the repository README).
+export function createServer({ base = process.env.AI_RESOURCES_API_URL || DEFAULT_BASE, fetchImpl = globalThis.fetch } = {}) {
+  base = base.replace(/\/+$/, '');
+
+  async function api(path, params = {}) {
+    const url = new URL(path, `${base}/`);
+    for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== '') url.searchParams.set(k, String(v));
+    const res = await fetchImpl(url, { headers: { Accept: 'application/json', 'User-Agent': `ai-resources-mcp/${VERSION}` } });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(body.error || `HTTP ${res.status} from ${url}`);
+    return body;
+  }
+
+  const guard = (fn) => async (args) => {
+    try {
+      return await fn(args);
+    } catch (e) {
+      return fail(`ai-resources: ${e.message}`);
+    }
+  };
+
+  const server = new McpServer({ name: 'ai-resources', version: VERSION });
+  const category = z.string().max(80).optional().describe('Category slug or name, e.g. "ai-developer-tools" (see list_categories)');
+  const limit = z.number().int().min(1).max(100).optional().describe('How many briefings (1-100, default 10)');
+
+  server.registerTool(
+    'search_briefings',
+    {
+      title: 'Search AI briefings',
+      description: 'Search daily AI news briefings (models, companies, funding rounds, tools, research) by keywords. All words must match. Newest first.',
+      inputSchema: { query: z.string().min(1).max(100).describe('Keywords, e.g. "anthropic claude" or "series a"'), category, limit, since: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Only briefings on or after this date (YYYY-MM-DD)') },
+    },
+    guard(async ({ query, category, limit = 10, since }) => {
+      const data = await api('api/articles', { q: query, category, limit, since });
+      return formatList(data, `${base}/search?q=${encodeURIComponent(query)}`);
+    }),
+  );
+
+  server.registerTool(
+    'latest',
+    {
+      title: 'Latest AI briefings',
+      description: 'The newest AI news briefings, optionally for one category. Use for "what is new in AI" questions.',
+      inputSchema: { category, limit },
+    },
+    guard(async ({ category, limit = 10 }) => {
+      const data = await api('api/articles', { category, limit });
+      // (the category's own slug from the API: a name passed in would give a link that 404s)
+      const slug = data.items?.[0]?.categorySlug;
+      return formatList(data, category && slug ? `${base}/categories/${slug}` : base);
+    }),
+  );
+
+  server.registerTool(
+    'get_briefing',
+    {
+      title: 'Read one briefing',
+      description: 'Full Markdown of one briefing, with every item, key points and source links. Pass its URL or slug from search_briefings/latest.',
+      inputSchema: { id: z.string().min(1).max(300).describe('Briefing URL (https://blogs.drix10.com/articles/...) or slug ("category/article-slug")') },
+    },
+    guard(async ({ id }) => {
+      const a = (await api('api/articles', { slug: id })).items?.[0];
+      if (!a) return fail(`No briefing found for "${id}".`);
+      return text(`# ${a.title}\n${a.date} | ${a.category}\n\n${a.content || a.description}\n\nSource: ${a.url}\n${DATA_LINE}`);
+    }),
+  );
+
+  server.registerTool(
+    'list_categories',
+    {
+      title: 'List categories',
+      description: 'Every briefing category with its slug and count. Use a slug as the category of search_briefings or latest.',
+      inputSchema: {},
+    },
+    guard(async () => {
+      const data = await api('api/categories');
+      const body = (data.items || []).map((c) => `- ${c.slug}: ${c.name} (${c.count})`).join('\n');
+      return text(`${body}\n\nSource: ${base}/categories\n${DATA_LINE}`);
+    }),
+  );
+
+  return server;
+}