@etsquare/sev-mcp 0.1.1 → 0.1.3

package/README.md

@@ -10,16 +10,16 @@ SEV searches its supported SEC corpus and returns a ranked company shortlist wit
 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.
+Each new start uses npm with --prefer-online to check the latest published version. Restart your MCP client after an update; an already-running process does not hot-update. No source checkout is required. The [Build page](https://etsquare.ai/build) shows the same setup for your platform.
 
-### Codex ? macOS / Linux
+### Codex - macOS / Linux
 
 Add to ~/.codex/config.toml:
 
 ```toml
 [mcp_servers.sev]
 command = "npx"
-args = ["-y","@etsquare/sev-mcp@0.1.1"]
+args = ["-y","--prefer-online","@etsquare/sev-mcp@latest"]
 startup_timeout_sec = 30
 tool_timeout_sec = 25
 
@@ -28,12 +28,12 @@ SEV_BASE_URL = "https://etsquare.ai"
 SEV_API_KEY = "YOUR_SEV_API_KEY"
 ```
 
-### Codex ? Windows
+### Codex - Windows
 
 ```toml
 [mcp_servers.sev]
 command = "cmd"
-args = ["/c","npx","-y","@etsquare/sev-mcp@0.1.1"]
+args = ["/c","npx","-y","--prefer-online","@etsquare/sev-mcp@latest"]
 startup_timeout_sec = 30
 tool_timeout_sec = 25
 
@@ -42,7 +42,7 @@ SEV_BASE_URL = "https://etsquare.ai"
 SEV_API_KEY = "YOUR_SEV_API_KEY"
 ```
 
-### Claude Desktop ? macOS / Linux
+### Claude Desktop - macOS / Linux
 
 Merge into your Claude Desktop configuration JSON:
 
@@ -53,7 +53,8 @@ Merge into your Claude Desktop configuration JSON:
       "command": "npx",
       "args": [
         "-y",
-        "@etsquare/sev-mcp@0.1.1"
+        "--prefer-online",
+        "@etsquare/sev-mcp@latest"
       ],
       "env": {
         "SEV_BASE_URL": "https://etsquare.ai",
@@ -64,7 +65,7 @@ Merge into your Claude Desktop configuration JSON:
 }
 ```
 
-### Claude Desktop ? Windows
+### Claude Desktop - Windows
 
 ```json
 {
@@ -75,7 +76,8 @@ Merge into your Claude Desktop configuration JSON:
         "/c",
         "npx",
         "-y",
-        "@etsquare/sev-mcp@0.1.1"
+        "--prefer-online",
+        "@etsquare/sev-mcp@latest"
       ],
       "env": {
         "SEV_BASE_URL": "https://etsquare.ai",
@@ -91,11 +93,11 @@ Merge into your Claude Desktop configuration JSON:
 - **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.
-
+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??
+Try: "Which retailers describe overseas factories or sourcing agents and exposure to higher merchandise costs?"
 
 ## Access and timeouts
 
@@ -111,6 +113,6 @@ Anonymous use is optional and requires explicit acceptance of the service's rele
 
 ## Support
 
-[Documentation](https://etsquare.ai/documentation) ? [Terms](https://etsquare.ai/terms) ? [Privacy](https://etsquare.ai/privacy) ? [Support](https://etsquare.ai/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

@@ -3,7 +3,72 @@ export class ApiError extends Error {
   constructor(code, message, status=0) {super(message);this.code=code;this.status=status;}
 }
 
+// Never forward provider/backend error text or unknown error codes to MCP callers.
+const PUBLIC_ERRORS = Object.freeze({
+  invalid_request:'Check the question, filters and requested result count.',
+  invalid_passage_id:'Use an original passage_id returned by SEV discovery.',
+  passage_not_found:'The original SEC passage is unavailable. Check the passage_id returned by discovery.',
+  unresolved_filter:'An explicit company or industry filter could not be resolved. Check the supplied filters.',
+  ambiguous_ticker:'An explicit ticker is ambiguous. Check the company filter.',
+  request_too_large:'The request is too large. Shorten the question or filters.',
+  authentication_required:'Configure your SEV API key to access this operation.',
+  authentication_failed:'Check that your SEV API key is valid and has not been revoked.',
+  insufficient_scope:'Your authorization does not permit this operation. Check your SEV connection.',
+  account_unavailable:'This SEV account is unavailable. Check your account at https://etsquare.ai/account.',
+  email_verification_required:'Verify your email address in your SEV account before continuing.',
+  rate_limited:'The request rate limit was reached. Try again shortly; no automatic retry was made.',
+  account_busy:'Your account already has research requests running. Wait for them to finish.',
+  service_busy:'SEV is busy. Try again later; no automatic retry was made.',
+  request_timeout:'SEV did not complete the request in time. No automatic retry was made; submitted work may still complete.',
+  quota_exhausted:'Your research allowance is exhausted. Check your SEV account allowance. Source passage retrieval does not consume a research request.',
+  anonymous_allowance_exhausted:'Your public trial allowance is exhausted. Sign in to SEV for account access.',
+  anonymous_capacity_reached:'Public trial capacity is exhausted for today. Sign in to SEV for account access.',
+  agreement_required:'Review and accept the current SEV terms in your account before continuing.',
+  legal_setup_pending:'SEV account setup is not ready. Try again later.',
+  subscription_inactive:'Your account entitlement is inactive. Check your SEV account.',
+  invalid_idempotency_key:'The request identifier is invalid. Check the client request identifier.',
+  idempotency_conflict:'This request identifier was used for different research. No additional discovery was started.',
+  request_already_recorded:'This request is already recorded. No additional discovery was started.',
+  origin_not_allowed:'The request origin is not permitted. Check your SEV connection configuration.',
+  interactive_signin_required:'Sign in to your SEV account to perform this operation.',
+  service_unavailable:'SEV is temporarily unavailable. Please try again later.',
+});
+function publicFailure(value, status, request) {
+  const supplied=value?.error?.code;
+  const fallback=status===401?'authentication_required':status===403?'insufficient_scope':
+    status===504?'request_timeout':status===429?'rate_limited':status===413?'request_too_large':
+    (status===400||status===422)?'invalid_request':'service_unavailable';
+  const code=typeof supplied==='string'&&Object.hasOwn(PUBLIC_ERRORS,supplied)?supplied:fallback;
+  let message=PUBLIC_ERRORS[code];
+  if(request&&(code==='unresolved_filter'||code==='ambiguous_ticker')) {
+    const details=value?.error?.invalid_filters;
+    const legacy=value?.error?.message;
+    let candidates=[];
+    // Legacy backend compatibility: only identifiers from known fixed formats.
+    if(typeof legacy==='string'&&legacy.length<=2048) {
+      const prefix='Explicit universe values were not found in the primary company catalog: ';
+      if(code==='unresolved_filter'&&legacy.startsWith(prefix))candidates=legacy.slice(prefix.length).split(', ');
+      if(code==='ambiguous_ticker') {
+        const match=legacy.match(/^Ticker ([A-Z0-9][A-Z0-9.\-^/]{0,19}) does not resolve to one CIK\.$/);
+        if(match)candidates=[match[1]];
+      }
+    }
+    const identified=[];
+    for(const [field,pattern] of [['tickers',/^[A-Z0-9][A-Z0-9.\-^/]{0,19}$/],['sic_codes',/^[0-9]{4}$/]]) {
+      if(code==='ambiguous_ticker'&&field!=='tickers')continue;
+      const supplied=Array.isArray(request[field])?request[field].slice(0,50):[];
+      const reported=Array.isArray(details?.[field])?details[field].slice(0,50):candidates;
+      const values=[...new Set(supplied.filter(v=>typeof v==='string').map(v=>v.trim().toUpperCase())
+        .filter(v=>pattern.test(v)&&reported.includes(v)))];
+      if(values.length)identified.push(field+': '+values.join(', '));
+    }
+    if(identified.length)message+=' Check '+identified.join('; ')+'.';
+  }
+  return new ApiError(code,message,status);
+}
+
 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);
@@ -32,8 +97,12 @@ export class SevClient {
       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);
+      let result;try{result=JSON.parse(new TextDecoder().decode(bytes));}catch{
+        if(!response.ok)throw publicFailure(null,response.status,body);
+        throw new ApiError('invalid_response','SEV returned an invalid JSON response. No automatic retry was made.');
+      }
+      if(!response.ok||result?.status==='error')throw publicFailure(result,response.status,body);
+      if(!result||typeof result!=='object'||Array.isArray(result))throw new ApiError('invalid_response','SEV returned an invalid response. No automatic retry was made.');
       return result;
     } catch(error) {
       if(error instanceof ApiError)throw error;
@@ -50,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,7 +19,7 @@ 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 server=new McpServer({name:'sev',version:'0.1.3'},{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};}
@@ -29,7 +29,7 @@ export function createServer(client=new SevClient()) {
     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.',
+    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.',
     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,6 +1,6 @@
 {
   "name": "@etsquare/sev-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "SEV company discovery and original SEC passage access over hosted REST.",
   "type": "module",
   "license": "MIT",