@etsquare/sev-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ETSquare AI, LLC
+
+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,116 @@
-# Temporary Holding Version
+# SEV 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.
+Ask a financial research question. Get relevant public companies and original SEC filing passages to investigate.
+
+SEV searches its supported SEC corpus and returns a ranked company shortlist with precise filing references. Your agent handles further analysis. Results are research leads; omissions and empty results are possible.
+
+## Connect
+
+1. Install [Node.js](https://nodejs.org/) 20.19 or later.
+2. Sign in at [etsquare.ai/account](https://etsquare.ai/account), accept the released Terms, and create an API key. Save its secret when shown.
+3. Add one of the configurations below, replace YOUR_SEV_API_KEY, and restart your MCP client. Keep your other server entries.
+
+The first start downloads this version from npm. No source checkout is required. The [Build page](https://etsquare.ai/build) shows the same setup for your platform.
+
+### Codex ? macOS / Linux
+
+Add to ~/.codex/config.toml:
+
+```toml
+[mcp_servers.sev]
+command = "npx"
+args = ["-y","@etsquare/sev-mcp@0.1.1"]
+startup_timeout_sec = 30
+tool_timeout_sec = 25
+
+[mcp_servers.sev.env]
+SEV_BASE_URL = "https://etsquare.ai"
+SEV_API_KEY = "YOUR_SEV_API_KEY"
+```
+
+### Codex ? Windows
+
+```toml
+[mcp_servers.sev]
+command = "cmd"
+args = ["/c","npx","-y","@etsquare/sev-mcp@0.1.1"]
+startup_timeout_sec = 30
+tool_timeout_sec = 25
+
+[mcp_servers.sev.env]
+SEV_BASE_URL = "https://etsquare.ai"
+SEV_API_KEY = "YOUR_SEV_API_KEY"
+```
+
+### Claude Desktop ? macOS / Linux
+
+Merge into your Claude Desktop configuration JSON:
+
+```json
+{
+  "mcpServers": {
+    "sev": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@etsquare/sev-mcp@0.1.1"
+      ],
+      "env": {
+        "SEV_BASE_URL": "https://etsquare.ai",
+        "SEV_API_KEY": "YOUR_SEV_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop ? Windows
+
+```json
+{
+  "mcpServers": {
+    "sev": {
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@etsquare/sev-mcp@0.1.1"
+      ],
+      "env": {
+        "SEV_BASE_URL": "https://etsquare.ai",
+        "SEV_API_KEY": "YOUR_SEV_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+- **discover_sec_companies**: required question; optional tickers **or** four-digit sic_codes, inclusive filed_since (YYYY-MM-DD), and max_companies (default 10, maximum 50). Explicit filters are never relaxed. There is no hidden date default.
+- **get_sec_passage**: retrieve a returned passage_id and available neighboring context without restarting discovery. Clients supporting MCP resources can also read sev://passages/{passage_id}.
+
+Passage IDs accept uppercase, lowercase or mixed-case hexadecimal. Returned IDs may use their canonical uppercase form.
+
+Returned references include company identity, accession, form, filing date, section, source URL and stable passage identifier. Optional previews are verbatim. Rankings describe research relevance, not investment merit or proof of current impact.
+
+Try: ?Which retailers describe overseas factories or sourcing agents and exposure to higher merchandise costs??
+
+## Access and timeouts
+
+Your account's evaluation allowance is shared by Playground, REST and MCP. A successful search consumes one discovery, including a valid empty result; failed searches do not. Source reads have a separate rate limit. Paid plans are coming soon.
+
+This is a local stdio MCP client of the hosted REST service, not a remote /mcp endpoint. SEV_BASE_URL is the service origin; the default is https://etsquare.ai. Do not append /SEV or /mcp. HTTPS is required except loopback HTTP for local development. A key created on a local service does not authorize production.
+
+The client has a 20-second HTTP deadline and no automatic discovery retry. Codex's example allows 30 seconds for startup (including the first npm download) and 25 seconds per tool call. Those settings belong to Codex; do not add them to Claude Desktop JSON. These are timeout limits, not response-speed guarantees. A submitted request may finish on the server if the caller stops waiting.
+
+Keep your key private, including in MCP configuration. Revoke it from Account when no longer needed. An invalid configured key never falls back to anonymous access. The client does not write credentials or cached research results to disk. Protocol messages alone go to stdout.
+
+Anonymous use is optional and requires explicit acceptance of the service's released Terms: read the Terms and Privacy Policy first, then set SEV_ACCEPT_TERMS_VERSION to the exact version you accepted. The client never accepts a new agreement automatically. A missing or outdated agreement fails before discovery. Use an account key for normal integrations.
+
+## Support
+
+[Documentation](https://etsquare.ai/documentation) ? [Terms](https://etsquare.ai/terms) ? [Privacy](https://etsquare.ai/privacy) ? [Support](https://etsquare.ai/support)
+
+MIT licensed thin client. This package is separate from the historical @etsquare/mcp-server-sec package.

package/client.mjs

@@ -0,0 +1,58 @@
+/** HTTP-only bridge. No Oracle credentials, models, automatic retries or disk state. */
+export class ApiError extends Error {
+  constructor(code, message, status=0) {super(message);this.code=code;this.status=status;}
+}
+
+export class SevClient {
+  constructor({baseURL=process.env.SEV_BASE_URL||'https://etsquare.ai', apiKey=process.env.SEV_API_KEY,
+               termsVersion=process.env.SEV_ACCEPT_TERMS_VERSION, fetchImpl=globalThis.fetch, timeout=20000}={}) {
+    const url=new URL(baseURL);
+    const local=['localhost','127.0.0.1','[::1]'].includes(url.hostname);
+    if ((url.protocol!=='https:'&&!(local&&url.protocol==='http:'))||url.username||url.password||url.search||url.hash||url.pathname!=='/')
+      throw new Error('SEV_BASE_URL must be an HTTPS origin, or an HTTP loopback origin for development.');
+    if(apiKey&&!/^sev_[A-Za-z0-9_-]{43}$/.test(apiKey))throw new Error('SEV_API_KEY is not a valid SEV key.');
+    if(termsVersion&&!/^[A-Za-z0-9._-]{1,60}$/.test(termsVersion))throw new Error('Invalid reviewed Terms version.');
+    if(!Number.isInteger(timeout)||timeout<1||timeout>60000)throw new Error('Invalid request timeout.');
+    this.base=url.origin;this.apiKey=apiKey;this.termsVersion=termsVersion;this.fetch=fetchImpl;this.timeout=timeout;this.cookie='';
+  }
+  async request(path, body, signal) {
+    const headers={'Accept':'application/json','X-SEV-Client':'mcp'};
+    if(this.apiKey)headers.Authorization='Bearer '+this.apiKey;
+    else if(this.cookie)headers.Cookie=this.cookie;
+    if(body!==undefined)headers['Content-Type']='application/json';
+    if(!this.apiKey&&path==='/v1/sec/discover-companies'&&this.termsVersion)headers['X-SEV-Terms-Version']=this.termsVersion;
+    let response;
+    try {
+      response=await this.fetch(this.base+path,{method:body===undefined?'GET':'POST',headers,redirect:'error',
+        ...(body===undefined?{}:{body:JSON.stringify(body)}),
+        signal:signal?AbortSignal.any([signal,AbortSignal.timeout(this.timeout)]):AbortSignal.timeout(this.timeout)});
+      if(!this.apiKey){const cookie=response.headers.get('set-cookie')?.match(/(?:^|,\s*)__session=([A-Za-z0-9_.-]+);/);if(cookie)this.cookie='__session='+cookie[1];}
+      const declared=Number(response.headers.get('content-length')||0);
+      if(declared>4194304)throw new ApiError('invalid_response','The SEV response exceeded the supported size.');
+      const reader=response.body?.getReader();let size=0;const parts=[];
+      if(reader){try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;if(size>4194304)throw new ApiError('invalid_response','The SEV response exceeded the supported size.');parts.push(value);}}finally{await reader.cancel();}}
+      const bytes=new Uint8Array(size);let offset=0;for(const part of parts){bytes.set(part,offset);offset+=part.length;}
+      let result;try{result=JSON.parse(new TextDecoder().decode(bytes));}catch{throw new ApiError('invalid_response','SEV returned an invalid JSON response.');}
+      if(!response.ok||result.status==='error')throw new ApiError(result.error?.code||'http_error',result.error?.message||'The SEV request failed.',response.status);
+      return result;
+    } catch(error) {
+      if(error instanceof ApiError)throw error;
+      if(signal?.aborted)throw new ApiError('request_cancelled','Stopped waiting. Work already submitted may continue on the server.');
+      throw new ApiError('service_unreachable','SEV could not be reached or the response timed out. No automatic retry was made.');
+    }
+  }
+  async discover(input,signal){
+    if(input.tickers?.length&&input.sic_codes?.length)throw new ApiError('invalid_request','Use tickers or SIC codes, not both.',422);
+    const result=await this.request('/v1/sec/discover-companies',input,signal);
+    if(result.status!=='ok'||!Array.isArray(result.companies)||typeof result.question!=='string')
+      throw new ApiError('invalid_response','SEV returned an invalid discovery response.');
+    return result;
+  }
+  async passage(id,signal){
+    if(!/^[a-f0-9]{32}$/i.test(id))throw new ApiError('invalid_passage_id','Use the passage_id returned by discovery.',400);
+    const result=await this.request('/v1/sec/passages/'+encodeURIComponent(id),undefined,signal);
+    if(typeof result.passage_id!=='string'||result.passage_id.toUpperCase()!==id.toUpperCase()||typeof result.text!=='string'||!Array.isArray(result.adjacent_passages))
+      throw new ApiError('invalid_response','SEV returned an invalid source response.');
+    return result;
+  }
+}

package/index.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import {McpServer, ResourceTemplate} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {z} from 'zod';
+import {pathToFileURL} from 'node:url';
+import {SevClient, ApiError} from './client.mjs';
+
+const date=z.string().regex(/^\d{4}-\d{2}-\d{2}$/).refine(value=>{
+  const d=new Date(value+'T00:00:00Z');return !Number.isNaN(d.getTime())&&d.toISOString().slice(0,10)===value&&value.slice(0,4)!=='0000';
+},'Use a real calendar date, YYYY-MM-DD.');
+const discovery=z.object({
+  question:z.string().trim().min(1).refine(s=>Array.from(s).length<=4000,'Maximum 4,000 characters.').describe('Natural-language SEC research question. Substantive alternatives and relationships matter.'),
+  tickers:z.array(z.string().trim().toUpperCase().regex(/^[A-Z0-9][A-Z0-9.\-^/]{0,19}$/)).max(50).optional().describe('Explicit company universe. Alternative to sic_codes; never relaxed.'),
+  sic_codes:z.array(z.string().regex(/^\d{4}$/)).max(50).optional().describe('Explicit four-digit industry codes, retaining leading zeroes. Alternative to tickers.'),
+  filed_since:date.nullable().optional().describe('Inclusive SEC filing date. No hidden date default.'),
+  max_companies:z.number().int().min(1).max(50).default(10),
+}).strict();
+const source=z.object({passage_id:z.string().regex(/^[A-Fa-f0-9]{32}$/)}).strict();
+const text=value=>({content:[{type:'text',text:JSON.stringify(value)}],structuredContent:value});
+
+export function createServer(client=new SevClient()) {
+  const server=new McpServer({name:'sev',version:'0.1.1'},{instructions:'SEV finds companies and original SEC passages worth investigating. Rankings indicate research relevance, not investment merit or proof of impact. Follow original sources. Do not automatically repeat a failed or uncertain discovery; it may already have used allowance. Use get_sec_passage for full text and adjacent context.'});
+  const call=operation=>async(input,extra)=>{
+    try{return text(await operation(input,extra.signal));}
+    catch(error){const known=error instanceof ApiError;return {...text({status:'error',error:{code:known?error.code:'client_error',message:known?error.message:'The SEV client could not complete the request.'}}),isError:true};}
+  };
+  server.registerTool('discover_sec_companies',{
+    title:'Discover SEC companies',description:'Find relevant public companies and one to three original SEC passages per company for a research question. Searches the supported indexed corpus; omissions and zero results are possible. Optional explicit tickers OR SICs and an inclusive filing-date cutoff. No synthesis or investment recommendation.',
+    inputSchema:discovery,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:false,openWorldHint:true},
+  },call((input,signal)=>client.discover(input,signal)));
+  server.registerTool('get_sec_passage',{
+    title:'Read discovered SEC passage',description:'Retrieve an original passage and available adjacent same-section context using a passage_id from discovery. Supporting source retrieval; no new search or JEV call.',
+    inputSchema:source,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true},
+  },call((input,signal)=>client.passage(input.passage_id,signal)));
+  server.registerResource('sec-passage',new ResourceTemplate('sev://passages/{passage_id}',{list:undefined}),{mimeType:'application/json'},
+    async(uri,{passage_id},extra)=>({contents:[{uri:uri.href,mimeType:'application/json',text:JSON.stringify(await client.passage(passage_id,extra.signal))}]}));
+  return server;
+}
+
+if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
+  try{await createServer().connect(new StdioServerTransport());}
+  catch{process.stderr.write('SEV MCP could not start. Check Node version and SEV configuration.\n');process.exitCode=1;}
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@etsquare/sev-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "SEV company discovery and original SEC passage access over hosted REST.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "bin": {
+    "sev-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "client.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "3.25.76"
+  },
+  "author": "ETSquare AI, LLC",
+  "homepage": "https://etsquare.ai/build",
+  "bugs": {
+    "url": "https://etsquare.ai/support"
+  },
+  "keywords": [
+    "mcp",
+    "sec",
+    "edgar",
+    "company-discovery",
+    "claude",
+    "codex"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}