Spedy NFS-e MCP

Spedy NFS-e 발행 및 상태 작업을 인증된 MCP Streamable HTTP 엔드포인트로 노출하는 Invokta Action Engine입니다.

엔진에는 세 가지 기능이 포함되어 있습니다:

• openapi.emitir-nfse: NFS-e를 생성하고 비동기 발행을 위해 대기열에 넣습니다.

• openapi.consultar-nfse: 하나의 NFS-e의 현재 상태를 읽습니다.

• openapi.listar-nfse: Spedy 필터와 페이지네이션으로 NFS-e 레코드를 나열합니다.

모든 기능은 인증된 주체가 필요합니다. Spedy 자격 증명은 서버 측에 유지되며 MCP 도구 입력으로 절대 허용되지 않습니다.

첫 실행

npm run check
npm run build
npm run mcp:http

포함된 로컬 구성은 http://127.0.0.1:3400/mcp에서 MCP를 제공합니다. 클라이언트는 Authorization: Bearer <MCP_BEARER_TOKEN>을 보내야 합니다.

커밋된 .env.example과 무시된 로컬 .env에는 모의 값이 포함되어 있습니다. 실제 요청을 하기 전에 MCP_BEARER_TOKEN과 SPEDY_API_KEY를 교체하십시오. 기본 커넥터 대상은 Spedy의 샌드박스입니다. 프로덕션은 절대 암시적으로 선택되지 않습니다.

Related MCP server: Receita Federal NFS-e: Notas Recebidas MCP

구성

발행은 비동기입니다. 성공적인 emitir-nfse 결과는 Spedy가 요청을 수락하고 대기열에 넣었음을 의미합니다. 승인 또는 거부를 관찰하려면 consultar-nfse 또는 Spedy 웹훅을 사용하십시오. 재시도를 멱등으로 만들려면 항상 안정적인 integrationId를 제공하십시오.

프로젝트 맵

• src/capabilities/는 도메인 작업과 해당 입력, 출력, 액세스 및 실행 계약을 소유합니다.

• src/engine.ts는 안정적인 기능 ID를 등록하고 엔진 소유 종속성을 제공합니다.

• src/direct.ts는 가장 작은 실행 가능한 스모크 경로입니다.

• test/engine.test.ts는 공개 엔진 경계를 통해 동작을 증명합니다.

• AGENTS.md는 프로젝트의 불가침 아키텍처 및 전달 규칙을 기록합니다.

• .agents/skills/develop-invokta-project/SKILL.md는 호환 에이전트에게 완전한 변경 워크플로를 제공합니다.

생성된 기능 검토

1. AGENTS.md와 생성된 개발 스킬을 읽으십시오.

2. 필요한 도메인 결과에 대한 실패하는 엔진 수준 테스트를 추가하십시오.

3. src/capabilities/ 아래의 모듈을 업데이트하거나 교체한 다음 src/engine.ts에 리터럴 기능 ID를 등록하십시오.

4. 직접 및 생성된 어댑터 진입점을 동일한 내보낸 엔진에 유지하십시오. 어댑터에서 기능 핸들러를 중복하지 마십시오.

5. npm run check를 실행한 다음 배포하기 전에 devtools에서 기능을 검사하십시오.

대화형 개발

npm run devtools

엔진을 빌드하고 Invokta devtools를 시작합니다. 일반적으로 http://localhost:4100/에서 실행됩니다. 명령이 출력한 URL을 열어 기능을 탐색하고, 선택한 실행 경로를 통해 스키마에서 생성된 JSON으로 호출하고, 실시간 호출 추적을 따르고, 테스트 ID를 전환하고, 의사 보고서를 읽으십시오. 소스 변경은 호스팅된 엔진을 자동으로 다시 빌드하고 다시 시작합니다.

읽기 전용 devtools 진단을 실행하려면:

npm run devtools:doctor

MCP HTTP 시작

npm run build
npm run mcp:http

서버를 패키징하고 기존 엔드포인트를 프로브하려면:

npm run deploy:package
npm run deploy:probe -- --url https://engine.example/mcp

배포 전에 생성된 모든 기능의 도메인 의미와 액세스 규칙을 검토하십시오.