@etsquare/sev-mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # SEV MCP
 
-Ask a financial research question. Get relevant public companies and original SEC filing passages to investigate.
+Ask a financial research question. In seconds, get a ranked shortlist of public companies, each with vetted original SEC filing passages and key reported financials: a few paragraphs per company instead of whole filings.
 
 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.
 

package/client.mjs

@@ -68,6 +68,7 @@ function publicFailure(value, status, request) {
 }
 
 export class SevClient {
+  #passageTail=Promise.resolve();
   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);
@@ -118,9 +119,24 @@ export class SevClient {
   }
   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;
+    const cancelled=()=>new ApiError('request_cancelled','Stopped waiting. Work already submitted may continue on the server.');
+    if(signal?.aborted)throw cancelled();
+    let onAbort;
+    const cancellation=signal?new Promise((_,reject)=>{
+      onAbort=()=>reject(cancelled());signal.addEventListener('abort',onAbort,{once:true});
+    }):null;
+    const run=this.#passageTail.then(async()=>{
+      // Once sent, request() owns cancellation and starts its existing timeout.
+      if(onAbort)signal.removeEventListener('abort',onAbort);
+      if(signal?.aborted)throw cancelled();
+      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;
+    });
+    // Absorb failure only on the queue tail; each caller still gets its own error.
+    this.#passageTail=run.then(()=>undefined,()=>undefined);
+    try{return await (cancellation?Promise.race([run,cancellation]):run);}
+    finally{if(onAbort)signal.removeEventListener('abort',onAbort);}
   }
 }

package/index.mjs

@@ -19,17 +19,17 @@ 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.2'},{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 server=new McpServer({name:'sev',version:'0.1.4'},{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.',
+    title:'Discover SEC companies',description:"Find public companies and evidence in indexed SEC 10-K and 10-Q filings. Use for industry-wide discovery, named-company research or peer comparisons.\n\nReturns ranked research leads with 1-3 passage previews per company, filing metadata and source links, not a synthesized answer. Inspect relevant originals with get_sec_passage before making factual or numerical claims; previews can omit key evidence and qualifications.\n\nWhen available, discovery includes consolidated financial context. Check each figure's own period, source and availability. Numeric conditions may be checked for supported measures, periods and scope; unknown or absent verdicts mean unverified. Returned companies are not guaranteed numerical matches. Figures do not establish causation.\n\nCoverage is bounded: max_companies is a ceiling; missing companies and empty results do not prove absence of evidence. tickers OR sic_codes restrict the universe. filed_since filters filing dates, not report periods. Exact period references may restrict filings; inspect reporting_period notices for fallback.\n\nEach successful request, including a valid empty result, consumes one research allowance unit. Run discoveries sequentially per account; concurrent requests may return account_busy. Do not automatically retry failed or uncertain requests.",
     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; does not consume a research allowance unit.',
+    title:'Read discovered SEC passage',description:"Read the full original SEC passage and available adjacent same-section context using a passage_id from discovery. Verify facts, amounts, dates, actual versus hypothetical disclosures, management explanations and qualifications before answering or citing. Context may omit referenced tables or other sections; do not infer missing facts or causation. No new discovery or model call; no research allowance unit consumed.",
     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'},

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@etsquare/sev-mcp",
-  "version": "0.1.2",
-  "description": "SEV company discovery and original SEC passage access over hosted REST.",
+  "version": "0.1.4",
+  "mcpName": "io.github.ETSquareAI/sev",
+  "description": "Ask a research question in plain English and, in seconds, get a ranked shortlist of public companies, each with vetted original 10-K/10-Q passages and key reported financials: a few paragraphs per company instead of whole filings. Limit the search to tickers or SIC codes to pinpoint passages in specific companies' filings.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -34,7 +35,13 @@
     "edgar",
     "company-discovery",
     "claude",
-    "codex"
+    "codex",
+    "sec-filings",
+    "10-k",
+    "10-q",
+    "financial-research",
+    "company-research",
+    "mcp-server"
   ],
   "publishConfig": {
     "access": "public",